Got it. In Prefect 3.x there isn’t a built-in “strict mode” for templating in

prefect.yaml

, so referencing an undefined Prefect Variable like

{{ prefect.variables.MY_VAR }}

will not automatically raise an error during template rendering. There’s no CLI flag or setting to change this behavior. Depending on when you want the failure to occur, here are two practical ways to enforce it: - Fail at deploy time (build/push sections) - Fail at run time (pull section or inside your flow) Option A — Fail the deployment if a variable is missing Add a validation step at the top of your

build:

(or

push:

) section that checks all referenced variables and exits non‑zero if any are missing. You can either hardcode the required variable names or parse them from the YAML. Minimal version (explicit list):

build:
  - utility.run_shell_script:
      id: validate-prefect-variables
      script: |
        python - <<'PY'
        import sys
        from prefect.variables import Variable

        required = ["MY_VAR", "OTHER_VAR"]  # put your variable names here
        missing = []
        for name in required:
            try:
                Variable.get(name)  # raises if not defined (when no default is provided)
            except Exception:
                missing.append(name)

        if missing:
            print(f"Missing Prefect Variables: {', '.join(missing)}", file=sys.stderr)
            sys.exit(1)

        print("All required Prefect Variables are defined.")
        PY

Automatic detection (parse variables referenced in prefect.yaml):

build:
  - utility.run_shell_script:
      id: validate-prefect-variables
      script: |
        python - <<'PY'
        import sys, pathlib
        from prefect.utilities.templating import find_placeholders
        from prefect.variables import Variable

        path = pathlib.Path("prefect.yaml")
        yaml_text = path.read_text()

        # Collect names referenced as {{ prefect.variables.NAME }}
        placeholders = find_placeholders(yaml_text)
        var_names = sorted({
            ph.name.split(".", 2)[-1]
            for ph in placeholders
            if getattr(ph, "type", None) and getattr(ph.type, "name", "") == "VARIABLE"
        })

        missing = []
        for name in var_names:
            try:
                Variable.get(name)  # will fail if not defined and no default is provided
            except Exception:
                missing.append(name)

        if missing:
            print(f"Missing Prefect Variables: {', '.join(missing)}", file=sys.stderr)
            sys.exit(1)

        print("All referenced Prefect Variables are defined.")
        PY

Option B — Fail at run time (best for variables used in the pull section) Variables referenced in

pull:

are resolved at flow run time by design. To fail fast when the worker starts the run, add a quick check at the start of your flow:

from prefect import flow
from prefect.variables import Variable

@flow
def my_flow():
    # Raises if MY_VAR is not defined (since no default is provided)
    Variable.get("MY_VAR")
    # continue with your logic...

Notes -

Variable.get("NAME")

raises if the variable does not exist and you do not pass a

default=

. If you provide

default=...

, it will not raise and will return that value instead. - If you also use environment variables (e.g.,

{{ $MY_ENV_VAR }}

), you can extend the validation script to check

os.environ[...]

similarly. Docs for reference - prefect.yaml and templating - Using Prefect Variables - Variables concept Quick question to tailor this exactly: do you want the deployment to fail if a variable is missing, or should the flow run fail at start-up if a variable is missing?