How to fix container is unhealthy in Docker

DockerINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 292 views

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.

Quick fix

Fixes container is unhealthy

# 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}}"
  1. Check container health status details
  2. View container logs
  3. Test the health check manually
  4. Adjust health check parameters
docker — error
# 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}}"
container is unhealthy

What this error means

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.

Typical symptoms

  • Container shows status as unhealthy in docker ps
  • Dependent services in Compose fail to start (condition: service_healthy)
  • Health check passes initially but fails after some time
  • Container runs but health status shows unhealthy
  • Orchestrator keeps restarting the container

Common causes

  1. Application inside container crashed or is not responding
  2. Health check endpoint returns error status
  3. Health check command is misconfigured
  4. Health check timeout is too short for slow-starting apps
  5. Network issue prevents health check from reaching service
  6. Required dependencies not available (database, external service)
  7. Application running but not ready to accept connections

How to fix "container is unhealthy"

1Check container health status details

View the health check output:

bash
# 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.

2View container logs

Check application logs for errors:

bash
# 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.

3Test the health check manually

Run the health check command inside the container:

bash
# 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 healthy

This helps identify if the check command itself is wrong.

4Adjust health check parameters

Health checks may need tuning for your application:

dockerfile
# In Dockerfile
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl -f http://localhost:8080/health || exit 1
yaml
# In docker-compose.yml
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 60s

Increase start_period for slow-starting applications.

5Check application dependencies

Ensure required services are available:

bash
# 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 DATABASE

The app may be unhealthy because it cannot connect to dependencies.

6Fix or disable health check temporarily

To debug without health check interference:

bash
# Run without health check
docker run --no-healthcheck <image>

# Override in Compose
healthcheck:
  disable: true

Once the application issue is fixed, re-enable health checks.

Advanced notes

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:

yaml
depends_on:
  db:
    condition: service_healthy

Custom Health Endpoints: Create a /health endpoint that checks internal state, database connections, and critical dependencies. Return 200 for healthy, 500+ for unhealthy.

Frequently asked questions

What does "container is unhealthy" mean?
Docker health checks allow you to monitor whether a container application is functioning correctly. " 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.
How do I fix "container is unhealthy"?
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.
What causes "container is unhealthy"?
Application inside container crashed or is not responding Health check endpoint returns error status Health check command is misconfigured
Is the "container is unhealthy" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading