Skip to content

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

✗ Broken code
# 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
✓ Fixed code
# 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: 3

Increasing 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

← Back to language