The container health check is failing. The application inside may not be ready, the health check command may be misconfigured, or the service has crashed. Check container logs and health check output.
Docker health checks allow you to monitor whether a container application is functioning correctly. When a health check command returns a non-zero exit code, Docker marks the container as "unhealthy." This does not stop the container but indicates the application inside is not responding as expected. Orchestration tools like Docker Compose, Swarm, or Kubernetes use health status to manage container lifecycle and dependencies.
View the health check output:
# See health status and recent check results
docker inspect --format "{{json .State.Health}}" <container_name> | jq
# Quick status check
docker ps --filter "name=<container_name>" --format "{{.Status}}"This shows the last few health check results and exit codes.
Check application logs for errors:
# View recent logs
docker logs <container_name>
# Follow logs in real-time
docker logs -f <container_name>
# Check for crash/restart patterns
docker logs --tail 100 <container_name>Look for application startup errors or crash messages.
Run the health check command inside the container:
# Get into the container
docker exec -it <container_name> sh
# Run the health check command manually
# Example for curl-based check:
curl -f http://localhost:8080/health
echo $? # Should be 0 for healthyThis helps identify if the check command itself is wrong.
Health checks may need tuning for your application:
# In Dockerfile
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
CMD curl -f http://localhost:8080/health || exit 1# In docker-compose.yml
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 60sIncrease start_period for slow-starting applications.
Ensure required services are available:
# Check if database is reachable from container
docker exec <container_name> nc -zv db-host 5432
# Check DNS resolution
docker exec <container_name> nslookup api-service
# Verify environment variables
docker exec <container_name> env | grep DATABASEThe app may be unhealthy because it cannot connect to dependencies.
To debug without health check interference:
# Run without health check
docker run --no-healthcheck <image>
# Override in Compose
healthcheck:
disable: trueOnce the application issue is fixed, re-enable health checks.
Health Check Best Practices:
- Use lightweight checks (simple HTTP endpoint, not complex operations)
- Start_period should exceed application startup time
- Interval should balance responsiveness with resource usage
- Retries give temporary issues time to resolve
Compose Dependencies: Use depends_on with condition for service ordering:
depends_on:
db:
condition: service_healthyCustom Health Endpoints: Create a /health endpoint that checks internal state, database connections, and critical dependencies. Return 200 for healthy, 500+ for unhealthy.
image operating system "linux" cannot be used on this platform
How to fix 'image operating system linux cannot be used on this platform' in Docker
manifest unknown: manifest unknown
How to fix 'manifest unknown' in Docker
cannot open '/etc/passwd': Permission denied
How to fix 'cannot open: Permission denied' in Docker
Error response from daemon: failed to create the ipvlan port
How to fix 'failed to create the ipvlan port' in Docker
toomanyrequests: Rate exceeded for anonymous users
How to fix 'Rate exceeded for anonymous users' in Docker Hub