EC
Health check failing
DockerWARNINGNotableRuntimeHIGH confidence

Container is running but reported as unhealthy

What this means

This status occurs when a container has a configured HEALTHCHECK, and the command specified by that check is failing. The container is still running, but Docker or the orchestrator considers it 'unhealthy', which may lead to it being restarted or removed from service.

Why it happens
  1. 1The application inside the container is unresponsive, failing, or has not finished starting up.
  2. 2The health check command itself is incorrect (e.g., wrong path, bad syntax).
  3. 3A dependency the application needs (like a database) is unavailable, causing the health check endpoint to fail.
  4. 4The health check is too aggressive, with a timeout or interval that is too short for the application to respond.
How to reproduce

An Nginx container is running, but its HEALTHCHECK is configured to curl a non-existent path '/status', causing it to fail.

trigger — this will error
trigger — this will error
# Dockerfile
FROM nginx
HEALTHCHECK --interval=5s --timeout=3s CMD curl -f http://localhost/status || exit 1

# After running a container from this image:
docker ps

expected output

CONTAINER ID   IMAGE     COMMAND                  CREATED          STATUS                    PORTS     NAMES
a1b2c3d4e5f6   my-app    "nginx -g 'daemon of…"   About a minute ago   Up About a minute (unhealthy)   80/tcp    my-web

Fix 1

Inspect the Health Check Logs

WHEN You need to see the output and reason for the failure.

Inspect the Health Check Logs
docker inspect --format='{{json .State.Health}}' my-web

Why this works

This command reveals the detailed status of the last few health checks, including the exit code and the first few lines of stdout/stderr from the failing command.

Fix 2

Adjust the Health Check Command or Parameters

WHEN The check is misconfigured or too aggressive.

Adjust the Health Check Command or Parameters
# Make the check more lenient or fix the command
HEALTHCHECK --interval=15s --timeout=5s --start-period=30s 
  CMD curl -f http://localhost/ || exit 1

Why this works

Fixing the command (e.g., to a valid path like '/') or increasing the interval, timeout, and adding a 'start-period' gives the application more time to start up and respond, preventing false negatives.

What not to do

✕ Make the health check 'CMD exit 0'.

This renders the health check useless. It will always report healthy, even if the application is completely frozen, defeating the purpose of monitoring.

Sources
Official documentation ↗

Dockerfile HEALTHCHECK instruction reference

Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev

← All Docker errors