unhealthy 🐳 Docker

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.

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:

🧠 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.