Health check fails: container marked unhealthy
Quick summary
Your container's health check is failing — the health check command returns a non-zero exit code.
Why this happens
The health check endpoint or command is not ready when the check runs
The health check interval or start period is too short for the application to initialize
The health check command itself has an error or tests the wrong endpoint
Minimal example
# docker-compose.yml
services:
app:
image: myapp:latest
healthcheck:
test: ['CMD', 'curl', '-f', 'http://localhost:3000/health']
interval: 5s
start_period: 2s # too short — app needs 10s to start# docker-compose.yml
services:
app:
image: myapp:latest
healthcheck:
test: ['CMD', 'curl', '-f', 'http://localhost:3000/health']
interval: 10s
start_period: 30s # enough time for app to initialize
retries: 3Increasing the start period to 30s gives the application enough time to initialize before health checks begin.
How to diagnose
Inspect the container health status with docker inspect and check the health log
Manually run the health check command inside the container to see the error
Review the health check configuration for correct interval, timeout, and start period
How to fix
Increase the start period to give the application more time to initialize
Fix the health check command to test the correct endpoint or condition
Add retry logic or increase the retries count for transient health check failures
How to prevent
Set appropriate health check intervals and start periods based on application startup time
Test the health check command manually before adding it to the container configuration
Related Resources
Related Glossary
Related Lessons
- Container Health
Learn about health checks.