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.
Container exited with code 128: invalid exit argument
How to fix 'Container exited with code 128' in Docker
Error response from daemon: Get https://registry-1.docker.io/v2/: Proxy Authentication Required
How to fix 'Proxy Authentication Required' in Docker
error exporting cache: failed to export cache
How to fix 'error exporting cache: failed to export cache' in Docker
net/http: TLS handshake timeout
How to fix 'net/http: TLS handshake timeout' in Docker
Docker container exited with code 255
How to fix 'Container exited with code 255' in Docker