Robert Szomolanyi
04/02/2026, 12:22 PMMarvin
04/02/2026, 12:22 PMMarvin
04/02/2026, 12:26 PMprefect worker start --pool <your-work-pool> --work-queue <your-queue>
2) Enable debug logs on the worker
You’ll get more detail about what’s blocking submission:
export PREFECT_LOGGING_LEVEL=DEBUG
prefect worker start --pool <your-work-pool> --work-queue <your-queue>
3) Verify the worker can actually start a subprocess for your deployment
- Check that the working directory configured for the deployment is valid on the worker host.
- If you’ve overridden the command or base job template, try running that command manually on the worker machine.
- Confirm required environment variables/secrets are present on the worker.
4) Check the Prefect UI for one affected run
- Open a Pending run → Details → State history. Look for any messages around “submitting” or failures during submission. Also check the run’s logs (if stream_output is on) for early process errors.
5) Confirm worker health and capacity
- The worker should show Online in the Work Pools page.
- Make sure it’s subscribed to the correct work queue(s) and isn’t at max capacity (limit) or starved for CPU/RAM.
If it persists, please share:
- Prefect version (server/Cloud and worker), OS of the worker host.
- A single example run ID and its deployment config (working_dir, any custom command/base_job_template).
- Whether a worker restart helped and any new DEBUG-level log lines after restart.
References
- States (incl. Pending definition): Prefect docs: States
- Workers overview (incl. process worker): Prefect docs: Workers
- Process worker API reference: API reference: Process worker
- Troubleshooting stuck runs / worker issues: Troubleshoot runs and workersRobert Szomolanyi
04/02/2026, 12:43 PMMarvin
04/02/2026, 12:44 PMMarvin
04/02/2026, 12:49 PMimport asyncio
from prefect.client.orchestration import get_client
from prefect.client.schemas.filters import (
FlowRunFilter, FlowRunFilterState, FlowRunFilterStateType
)
from prefect.states import Scheduled
async def main():
async with get_client() as client:
# Adjust filters (e.g., by deployment, tags) to target the right runs
runs = await client.read_flow_runs(
flow_run_filter=FlowRunFilter(
state=FlowRunFilterState(
type=FlowRunFilterStateType(any_=["PENDING"])
)
),
limit=500, # tune batch size
)
for r in runs:
await client.set_flow_run_state(
r.id,
Scheduled(message="Rescheduled from Pending"),
force=True, # override if a worker was mid-submission
)
asyncio.run(main())
Notes:
- There’s no CLI bulk retry for Pending; prefect flow-run retry only applies to terminal states (Completed/Failed/Cancelled/Crashed).
- If a worker is actively submitting a run, forcing state changes can race—consider pausing/restarting the worker first or scoping the script narrowly (e.g., by deployment).
If you want, tell me which deployment(s) or filters to use (deployment name, tags, work pool/queue), and I’ll tailor a safe, scoped script for your environment.
Helpful docs
- Troubleshooting stuck runs/workers: Troubleshoot runs and workers