Docker Container "unhealthy" - Fix Failing HEALTHCHECK in CI

By Kaveh Alemi·Latchkey

A container’s HEALTHCHECK probe kept failing, so Docker marked it unhealthy - which then blocks anything waiting on its health (often a compose depends_on: condition: service_healthy).

What this error means

In CI, a service comes up but docker ps shows (unhealthy), and a dependent step or service fails with dependency failed to start: container X is unhealthy. The app may actually be fine; the probe is what is failing.

docker output

dependency failed to start: container db is unhealthy
# docker ps:  Up 40 seconds (unhealthy)

Common causes

Probe command is wrong or missing tools

The HEALTHCHECK runs a command (e.g. curl, pg_isready) that is not installed in the image or targets the wrong port/path, so it always reports failure.

Start period too short for slow startup

Databases and JVM apps can take longer to become ready than the --start-period/interval allows, so health checks fail before the app is up.

App genuinely not ready

The service really has not finished initializing (migrations, warmup), so the probe correctly reports unhealthy.

How to fix it

Make the probe match the app and tools available

Use a check that exists in the image and targets the right endpoint, with a realistic start period.

Dockerfile

HEALTHCHECK --interval=10s --timeout=3s --start-period=30s --retries=5 \
  CMD pg_isready -U postgres -h 127.0.0.1 || exit 1

Inspect the health log to see why it fails

Read the recorded probe output to distinguish a bad probe from a slow app.

Terminal

docker inspect --format '{{json .State.Health}}' db | jq

How to prevent it

Set start_period to cover real startup time for slow services.
Use probe commands and tools guaranteed to exist in the image.
Test healthchecks locally before relying on service_healthy in CI.

Frequently asked questions

What causes ""container is unhealthy""?

The HEALTHCHECK runs a command (e.g. curl, pg_isready) that is not installed in the image or targets the wrong port/path, so it always reports failure.

How do I fix "container is unhealthy"?