Docker — container marked unhealthy by its healthcheck

Fix Docker unhealthy containers by correcting the healthcheck command, timing and the endpoint it probes.

beginnerdebuggingdockerhealthcheck

Symptoms

Container status shows (unhealthy)
The app is running but the healthcheck keeps failing
Dependencies do not start because the container never becomes healthy
Health checks pass manually but fail in the container

Possible causes

The healthcheck command is not available inside the image
Start period is too short so checks fail during boot
The probed endpoint returns an error though the app is up
The healthcheck probes localhost while the app binds elsewhere

Diagnosis steps

Run the check manually in the container

docker exec container sh -c "<healthcheck command>"

Interpretation

Reproducing the exact command inside the container shows whether the tool exists and the endpoint responds.

Inspect health status and logs

docker inspect --format "{{json .State.Health}}" container

Interpretation

The health log entries contain each check output, revealing the command failure or the failing endpoint.

Give the app time to start

healthcheck: start_period: 30s

Interpretation

A start period suppresses failures during boot so slow starters are not marked unhealthy prematurely.

Root cause

The healthcheck command failed repeatedly because the probe was wrong, the required tool was absent from the image, or the start period was too short for the application to become ready.

Fix

Use a probe that exists in the image and targets the correct address, tune interval, timeout, retries and start_period to the application, and ensure the endpoint reflects real readiness.

Verify the fix

Restart the container and confirm it reaches healthy, and confirm dependent services start once it does.

Symptom walkthrough

A container shows as unhealthy even though the application appears to run. Health status drives orchestration, so an unhealthy container can block dependencies or be restarted repeatedly. The failure usually comes from a probe that is not present in the image, an endpoint that does not reflect readiness, a wrong address, or a start period shorter than the real boot time.

Fix in practice

Make the probe use a tool that exists in the image and target the correct host and port, then tune interval, timeout, retries and start period to the application. The endpoint should represent real readiness, not merely that the process is alive, so it matches how orchestration decides to route traffic.

Verification

Restart the container and confirm it reaches healthy, then confirm dependent services start now that the health gate passes. Healthy status plus working dependents confirms the probe matches reality.

Diagnostic commands

Check the behavior with commands like these:

docker exec container sh -c "<healthcheck command>"
docker inspect --format "{{json .State.Health}}" container
healthcheck: start_period: 30s