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.
container is unhealthydependency failed to start: container is unhealthyHealth check failed 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
- Read the check output: docker inspect --format '{{json .State.Health}}' c
- Use a tool that exists in the image, or install curl
- Increase start_period/retries
Detailed fix by platform
Docker Compose
- `healthcheck: test: ["CMD-SHELL", "wget -qO- http://localhost:3000/health
- exit 1"] interval: 10s timeout: 3s retries: 5 start_period: 30s`
How to diagnose
- Health log — State.Health.Log output
- Tool — Is curl/wget in the image?
- 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:
Similar errors
- ACR unauthorized Azure Container Registry: unauthorized: authentication required, visit https://aka.ms/acr/authorization (AKS ErrImagePull 401)
- compose validation docker compose: services.x Additional property y is not allowed / yaml: line N: mapping values are not allowed
- Conflict container name Conflict. The container name "/x" is already in use by container …
Most viewed in Docker
- docker-credential-desktop error getting credentials - err: exec: "docker-credential-desktop": executable file not found in $PATH
- pull access denied pull access denied for image, repository does not exist or may require 'docker login'
- lookup registry-1.docker.io: no such host dial tcp: lookup registry-1.docker.io: no such host / Temporary failure in name resolution during docker build
Other ways to find it
Where this error sits
Origin: Platform & cloud. Errors that are often confused with or caused by this one (click to open):
🧠 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.
Report a correction or suggest an improvement
Last updated 13 Oct 2026