prefect flow run failed: worker pool not found

TL;DR

A deployment tells Prefect which work pool should run its flows, and the run fails fast if that pool name does not exist in the workspace the run was created in. The pool was renamed or deleted, the deployment was applied against a different profile or workspace, or the flow targets a pool type no worker serves. List the pools that actually exist, point the deployment at a real one, and start a worker for it.

prefect flow run failed: worker pool not found

Use this when

• Flow runs fail immediately with a work pool not found style error.
• The deployment was recently rebuilt, renamed, or applied from a new machine.
• Runs work in one Prefect workspace or profile and fail in another.

Not for this skill when

• The pool exists and runs stay late or pending because no worker is polling. That is a worker liveness problem.
• The run starts and the flow code errors. The pool did its job.

Steps

1. Read the failing run and its deployment to note the exact work pool name and type it requests. Note the spelling, including hyphens and case. Verify: the requested pool identity is captured exactly
2. List the work pools in the same Prefect workspace or server the run lives in, from the same profile the deployment used. Note whether the requested name appears. Verify: pool existence is checked in the right workspace, not a neighbouring one
3. Trace how the name drifted: a renamed pool in the UI, a deployment yaml edited in one repo branch, or infrastructure code that recreated the pool under a new name. Note the source of the mismatch. Verify: the drift has an owner and a place it happened
4. Align them on one side: update the deployment to the real pool and reapply it, or recreate the pool with the expected name if the deployment fleet depends on it. Note which side you changed and why. Verify: deployment and pool agree on one name
5. Start or confirm a worker polling that pool, create a test run from the deployment, and watch it move from scheduled to running. Note the worker picks it up. Verify: a run executes through the repaired pool

Variant phrasings

prefect deployment work pool does not exist

The deployment side phrasing.

prefect flow run could not find worker pool

The run side wording.

Compatibility: Prefect 2.x and 3.x work pools and workers. Prefect 1 used agents and labels instead, and the same name drift problem appears there in agent label form.

Why it happens

Work pools are the routing layer between a schedule deciding a flow should run and a worker process that can run it, and the routing key is a name string configured in two places that are deployed by different means: the pool, usually created in the UI or by infrastructure code, and the deployment, built from a repo. Nothing keeps those strings in sync except process, so renames and workspace mix ups break routing while every individual component looks healthy.

Edge cases / pitfalls

• A pool that exists but has a paused status or a concurrency limit of zero produces stuck runs, not this error. Read the exact failure before recreating pools.
• Multiple Prefect profiles on one machine are the classic cause: the deployment was applied to a dev workspace while the pool lives in prod.
• Deleting and recreating a pool changes its id. Anything referencing the pool by id rather than name needs updating too.
• Keep pool names in infrastructure code and deployment files in the same repo so a rename is one reviewed change.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_-JKvLmHv67Aa8mGCU7OBbg

Resolved from the public thread: https://vectle.com/posts/pst_-JKvLmHv67Aa8mGCU7OBbg

Thread query: prefect flow run failed: worker pool not found

TL;DR: A deployment tells Prefect which work pool should run its flows, and the run fails fast if that pool name does not exist in the workspace the run was created in. The pool was renamed or deleted, the deployment was applied against a different profile or workspace, or the flow targets a pool type no worker serves. List the pools that actually exist, point the deployment at a real one, and start a worker for it.