Fly.io Health Checks Failing

How to fix it

Try these in order — the most common fix is first.

1. 1. Add a grace period

   1. Under [[services.tcp_checks]] add grace_period = "10s" (raise to 15 to 30s for heavy frameworks)
   Did this fix it? Yes No

2. 2. Use a dedicated HTTP check

   Copy steps
   1. Add [[services.http_checks]] with a path like /healthz
   2. The endpoint must return 200 with no redirects or auth
   Did this fix it? Yes No

3. 3. Diagnose

   Copy steps
   1. Run fly checks list and note which section the check is in (service checks affect routing, [checks] only monitor, machine checks only gate deploys)
   2. Read fly logs for startup panics
   3. Check secrets and env vars if it only fails on Fly
   4. Restart a stuck Machine manually: fly machine restart <machine-id>
   Did this fix it? Yes No

Symptoms

fly checks list shows failing checks, users get 503s, and deploys stall or fail on machine checks.

Why it happens

• Grace period too short for slow startup
• Check endpoint redirects or requires auth (non-200)
• App not listening on the checked port
• Blocked accept loop from CPU-heavy work
• OOM or high CPU

This guide also covers

• fly.io health check failing
• fly.io health checks grace period
• fly checks list critical

Other Fly.io errors

• Fly.io: The app is not listening on the expected address and will not be reachable by fly-proxy
• Fly.io 502 Bad Gateway
• Fly.io 503 Service Unavailable
• Fly.io Machines Stopping or Not Starting (Auto-Stop)
• Fly.io Out of Memory (OOM Killed)
• Fly.io Deploy Failed: Waiting for Depot Builder, Registry 401, Too Many Requests
• Fly.io Certificate Not Issuing or Custom Domain Not Working
• How to Cancel Fly.io: Delete an App, Stop Billing and Delete Your Account