BahriyaBAHRIYAby Mamluk

Health Check Failures

Bahriya restarts a container whose health check fails repeatedly, and it won't serve traffic to a replica that isn't healthy. When a health check fails, the fix is to make the health check path return a 2xx response quickly and reliably.

Updated 3 Aug 20262 min read

Bahriya restarts a container whose health check fails repeatedly, and it won't serve traffic to a replica that isn't healthy. When a health check fails, the fix is to make the health check path return a 2xx response quickly and reliably.

Symptoms

  • The container restarts on a loop, or replicas never become healthy.
  • A newly deployed version never takes over traffic.
  • The container starts fine, then becomes unhealthy under load or after some time.

Likely causes

  • The health check path is wrong. It points at a route that doesn't exist, so the application returns a 404.
  • The endpoint returns a non-2xx status. Any status other than 2xx is treated as unhealthy.
  • The health check path requires authentication. If the endpoint sits behind auth, the probe can't reach a success response.
  • Startup is slower than the bootstrap time. The application isn't ready before the startup window closes, so it's restarted.
  • The application degrades later — running out of memory, exhausting connections, or deadlocking — and the liveness check fails.

How to fix

  1. Confirm the path exists and returns a 2xx status. A dedicated lightweight endpoint such as /health or /healthz is the safest choice.
  2. Leave the health check unauthenticated. The probe can't supply credentials, so the path must return success without auth. Keep it separate from any protected routes.
  3. Keep it fast and cheap. The endpoint should respond in under a second and avoid database queries or external calls, so a slow dependency doesn't fail the check.
  4. Raise the bootstrap time if the application needs longer to initialise — for example, when loading large datasets or running migrations. A good rule of thumb is roughly twice your typical startup time.
  5. Read the logs around a restart. If the container was healthy and then failed, check for memory pressure, connection limits, or deadlocks in the application logs. See Container Out of Memory.
Note

The single most common cause is a health check path that returns 404 because the route was never added to the application. Confirm the exact path responds with a 2xx before looking anywhere else.