Learn how to monitor worker health and automatically restart workers when they become unresponsive.
--with-healthcheck
flag:
/health
endpoint.
When enabled, the worker exposes an HTTP endpoint at:
{"message": "OK"}
when the worker is healthy{"message": "Worker may be unresponsive at this time"}
when the worker is unhealthyPREFECT_WORKER_QUERY_SECONDS * 30
seconds, it is considered unhealthy
and its health endpoint will return 503 (Service Unavailable). With default settings, a worker is unhealthy if it hasn’t polled in 450 seconds (7.5 minutes).
This generous threshold accounts for temporary network issues, API unavailability, or brief worker pauses without triggering false alarms.
--with-healthcheck
http://localhost:8080/health
)PREFECT_WORKER_WEBSERVER_PORT
prefect config view --show-defaults | grep WORKER
PREFECT_LOGGING_LEVEL=DEBUG
on the worker to see detailed polling activityPREFECT_WORKER_QUERY_SECONDS=5
PREFECT_WORKER_QUERY_SECONDS
if your API has high latencyPREFECT_API_URL
is correctly configured and accessiblePREFECT_WORKER_HEARTBEAT_SECONDS
: How often workers send heartbeats to the API (default: 30)PREFECT_WORKER_QUERY_SECONDS
: How often workers poll for new flow runs (default: 15)PREFECT_WORKER_PREFETCH_SECONDS
: How far in advance to submit flow runs (default: 10)PREFECT_WORKER_WEBSERVER_HOST
: Health server host (default: 127.0.0.1)PREFECT_WORKER_WEBSERVER_PORT
: Health server port (default: 8080)