unhealthy Docker Origin: Platform & cloud OSI layer 7 · Application Last updated 13 Oct 2026

Docker container is unhealthy (health check failing)

The container is running, but its HEALTHCHECK command keeps failing, so Docker (and dependent services) consider it unhealthy.

Exact message you may see container is unhealthydependency failed to start: container is unhealthyHealth check failed
Seen on: Docker

Meaning

Health checks run inside the container. They fail when the app isn’t listening yet, the check uses curl/wget that isn’t installed in the image, it targets the wrong port, or start-up is slower than start_period. Compose services with depends_on: condition: service_healthy then never start.

Common causes

  • Health check tool (curl/wget) missing from the image
  • Wrong port/path in the check
  • App slow to start — start_period too short
  • App genuinely unhealthy (DB unreachable)

⚡ Quick fix

  1. Read the check output: docker inspect --format '{{json .State.Health}}' c
  2. Use a tool that exists in the image, or install curl
  3. Increase start_period/retries

Detailed fix by platform

Docker Compose

  1. `healthcheck: test: ["CMD-SHELL", "wget -qO- http://localhost:3000/health
  2. exit 1"] interval: 10s timeout: 3s retries: 5 start_period: 30s`

How to diagnose

  1. Health log — State.Health.Log output
  2. Tool — Is curl/wget in the image?
  3. Port — Does the app listen on that port inside the container?

🔧 Still not fixed?

Many errors look alike. If the steps above didn’t solve it, one of these is probably what you’re facing:

Where this error sits

Origin: Platform & cloud. Errors that are often confused with or caused by this one (click to open):

ACR unauthorized — Azure Container Registry: unauthorized: authentication required, visit https://aka.ms/acr/authorization (AKS ErrImagePull 401) (Azure)ACR unauthorizedcompose validation — docker compose: services.x Additional property y is not allowed / yaml: line N: mapping values are not allowed (Docker)compose validationConflict container name — Conflict. The container name "/x" is already in use by container … (Docker)Conflict container na…Container failed to start — Cloud Run: The user-provided container failed to start and listen on the port defined provided by the PORT=8080 environment variable (Google Cloud / Firebase)Container failed to s…depends on undefined service — service "web" depends on undefined service "db": invalid compose project (Docker)depends on undefined …docker-compose: command not found — docker-compose: command not found / 'compose' is not a docker command (Docker)docker-compose: comma…Exited (0) — Docker container exits immediately (Exited (0) / Exited (1) right after start) (Docker)Exited (0)Health checks failed — ALB target unhealthy: Health checks failed with these codes: [404] / Request timed out (AWS)Health checks failedunhealthy

Explore the map of this error Full error map →

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.

💬 What worked for others

No tips yet — did something else fix this for you?

Share what worked for you

Tips are checked by an editor before they appear. Links are removed.