DockerMid

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 ps shows (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

  1. 1
    Read the health state and the last check output
    docker inspect --format '{{json .State.Health}}' CONTAINER

    Shows the status, the failing streak and the recent check results with their output.

  2. 2
    Run 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 curl that 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-period to 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

Sources

Docker documentation (docs.docker.com), read 18 Nov 2026 from the official docs repository.

Search

Search cheat sheets and projects