Container marked unhealthy: HEALTHCHECK failing
A container is unhealthy after its HEALTHCHECK fails the set number of retries. Read the last check output, then fix the command, timeout or start period.
What you see
docker psshows(unhealthy)- An orchestrator keeps replacing a container that seems to run fine
What it means
A container with a healthcheck has a health status as well as its normal status. It starts as starting, becomes healthy when a check passes, and becomes unhealthy after the configured number of consecutive failures. The check command signals health by its exit status: 0 healthy, 1 unhealthy.
Defaults per the Dockerfile reference: interval 30s, timeout 30s, start period 0s, retries 3. A check that takes longer than the timeout counts as failed, and the check process is killed with SIGKILL.
How to confirm the cause
- 1Read the health state and the last check output
docker inspect --format '{{json .State.Health}}' CONTAINERShows the status, the failing streak and the recent check results with their output.
- 2Run the check command by hand inside the container
docker exec CONTAINER sh -c 'THE_CHECK_COMMAND'; echo $?
Use the exact command from the HEALTHCHECK. Exit 0 is healthy.
Causes and fixes
The check command is not in the image
- HOW TO TELL
- The check output says the command was not found.
- ROOT CAUSE
- The check uses a tool such as
curlthat a slim image does not include, so every run fails. - FIX
- Use a tool that exists in the image, or add it. Make the check exit 0 for healthy and 1 for unhealthy.
The app needs longer to start than the retries allow
- HOW TO TELL
- It is unhealthy right after start, and healthy later if you wait.
- ROOT CAUSE
- With a 0s start period, failures during startup count toward the retries, so a slow starter is marked unhealthy before it is ready.
- FIX
- Set
--start-periodto cover startup. Failures in the start period are not counted, and the first success ends it.HEALTHCHECK --interval=30s --timeout=3s --start-period=60s --retries=3 \ CMD curl -f http://localhost:8080/health || exit 1
The check is too slow for its timeout
- HOW TO TELL
- The output shows a timeout.
- ROOT CAUSE
- The check takes longer than
--timeout, so it is killed and counted as a failure. - FIX
- Make the check cheaper, or raise
--timeout.
The app really is broken
- HOW TO TELL
- The check runs fine by hand and returns a failure.
- ROOT CAUSE
- The healthcheck is doing its job: the app is stuck or returning errors.
- FIX
- Fix the app. See its logs with
docker logs.
How to stop it coming back
- Keep the check cheap and local; do not call downstream services.
- Set a start period for anything that takes more than a few seconds to boot.
- Test the check command in CI.
Keep going
- Runbook: Compose service starts before its database is ready
- Runbook: Liveness probe failed: the container keeps being restarted
- Cheat sheet: Docker
- Cheat sheet: Docker Compose
- Lesson: the containers topic in Learn
Sources
Docker documentation (docs.docker.com), read 18 Nov 2026 from the official docs repository.