prefect deployment not found, flow run failed

TL;DR

The flow run references a deployment by name that does not exist in the environment it runs in: it was never created there, it was renamed, or the run targets the wrong Prefect server. Check the deployment list in the exact environment of the run. Deployment names are environment-scoped; creating it on your laptop does not create it in prod.

prefect deployment not found, flow run failed

Use this when

• A flow run fails with deployment not found.
• It works in one environment but not another.
• A deployment was renamed or deleted recently.

Not for this skill when

• The deployment exists but the schedule is wrong. Check the schedule config.
• The flow run starts but the flow fails. That is a flow problem.

Steps

1. List deployments in the environment the run targets and search for the name. Note whether it exists there. Verify: existence is verified in the right place
2. Check for renames: compare the run's deployment reference against current names. Note any rename. Verify: renames are caught
3. Verify the run points at the intended Prefect API: wrong server means a different deployment set. Note the API URL. Verify: the server is confirmed
4. Create or restore the deployment with the expected name and config. Note it appears in the list. Verify: the deployment exists
5. Re-trigger the flow run and confirm it resolves the deployment. Note the run starts. Verify: the fix is verified

Variant phrasings

prefect deployment does not exist

The paraphrase.

prefect deployment name mismatch

The rename-shaped search.

Compatibility: Prefect 2.x deployments. Deployment storage moved across 2.x minor versions; the not-found semantics are stable.

Why it happens

Deployments are server-side records tying a flow to infrastructure and schedules, and flow runs resolve them by name at launch time. Names are scoped to the Prefect API the run talks to, so the same name can exist in dev and be absent in prod. Renames break every trigger that used the old name, and deleted deployments leave their schedules' runs orphaned. The error is precise: the name lookup failed, so the fix is always about the name in that environment.

Edge cases / pitfalls

• Infrastructure blocks referenced by the deployment can also go missing and produce confusing errors. Check blocks too.
• Deployments created by CI with generated names change every run. Pin the name or update triggers to match.
• A deployment that exists but is paused still resolves; not-found is strictly about the name. Do not confuse the two.
• Multiple Prefect servers (dev, prod) with similar names invite pointing at the wrong one. Make the API URL visible in run metadata.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_W8-qWMNfM47f5dyNQGBtNQ