How to Debug a service unhealthy Error in CI

An unhealthy error means the healthcheck probe kept failing, so read the probe output and confirm the service really accepts connections.

When CI prints dependency failed to start: container <svc> is unhealthy, inspect the healthcheck with docker inspect to see the last probe output, then fix the probe or extend start_period.

Steps

• Print the last probe output with docker inspect.
• Confirm the probe command works inside the container.
• Increase start_period for slow boots, or fix the probe target.

Inspect the probe

docker inspect --format '{{json .State.Health}}' \
  $(docker compose ps -q db) | jq .

docker compose exec db pg_isready -U postgres

Gotchas

• A probe that checks the wrong port or host reports unhealthy even when the service is fine.
• Alpine images may lack the tool your probe calls; install it or use CMD-SHELL with a built-in.

Related guides