docker healthcheck ai_generated true

health check for container failed: unhealthy

ID: docker/docker-healthcheck-failing

Also available as: JSON · Markdown
88%Fix Rate
90%Confidence
50Evidence
2023-01-01First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
27 active — — —

Root Cause

Docker container health check is returning non-zero exit codes consistently. The container is marked unhealthy, which can prevent dependent services from starting.

generic

Workarounds

  1. 90% success Debug the health check command inside the container 
    docker exec <container> <healthcheck-command> to run the health check manually and see the actual error output

    Sources: https://docs.docker.com/reference/dockerfile/#healthcheck

  2. 85% success Add a start-period to allow the application time to initialize 
    HEALTHCHECK --start-period=30s --interval=10s --timeout=5s --retries=3 CMD curl -f http://localhost:8080/health || exit 1

    Sources: https://docs.docker.com/reference/dockerfile/#healthcheck

Dead Ends

Common approaches that don't work:

  1. Removing the HEALTHCHECK instruction to avoid the error 85% fail

    Hides the real problem; the service is genuinely unhealthy and orchestrators cannot detect failures

  2. Setting very long health check intervals to delay detection 70% fail

    Slow detection means unhealthy containers serve traffic longer, degrading user experience

Error Chain

Leads to:
Preceded by:
Frequently confused with: