How to Fix Docker Healthcheck Failing Error

In this tutorial, you'll learn about How to Fix Docker Healthcheck Failing Error. We cover key concepts, practical examples, and best practices.

Your container runs but Docker reports it as unhealthy — the healthcheck command is failing because of wrong endpoint, timeout, or missing dependencies inside the container.

The Problem

docker ps

Shows:

CONTAINER ID   IMAGE   COMMAND                  CREATED          STATUS                     PORTS
abc123         myapp   "node app.js"            10 seconds ago   Up 10 seconds (unhealthy)

Step-by-Step Fix

Step 1: Check the health status

docker inspect --format='{{.State.Health.Status}}' <container>

Expected: healthy, unhealthy, or starting.

Step 2: View healthcheck logs

docker inspect --format='{{json .State.Health.Log}}' <container> | jq

Sample output:

{
  "Start": "2026-06-24T10:00:00Z",
  "End": "2026-06-24T10:00:02Z",
  "ExitCode": 1,
  "Output": "curl: (7) Failed to connect to localhost port 8080"
}

Step 3: Fix the HEALTHCHECK in Dockerfile

# WRONG — too short timeout, wrong port
HEALTHCHECK --interval=5s --timeout=1s --retries=2 \
  CMD curl -f http://localhost:8080/health || exit 1

# RIGHT — appropriate values
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1

Step 4: Install curl or use an alternative

If curl is not in the image:

RUN apt-get update && apt-get install -y curl

Or use a shell-based check:

HEALTHCHECK CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

Step 5: Use docker-compose healthcheck

services:
  app:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Step 6: Depend on health in docker-compose

services:
  app:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
  nginx:
    depends_on:
      app:
        condition: service_healthy

Prevention Tips

• Include a /health endpoint in your application
• Set start_period to account for startup time
• Use curl -f or wget --spider for HTTP checks
• Do not use complex scripts — keep healthchecks simple
• Log healthcheck output to debug failures

Common Mistakes with healthcheck

1. Forgetting deriving (Show, Eq) on custom data types needed for debugging
2. Placing the wildcard pattern first in case expressions, making all subsequent patterns unreachable
3. Using head and tail instead of pattern matching, causing runtime errors on empty lists

These mistakes appear frequently in real-world DOCKER code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ