How to fix health check command returned non-zero exit code: 1 in Docker

What this error means

The "health check command returned non-zero exit code: 1" error in Docker indicates that the HEALTHCHECK instruction defined in your Dockerfile or docker-compose.yml has failed. Docker's health check mechanism periodically runs a command inside your container to verify the service is working correctly. When the health check command exits with code 0, Docker marks the container as "healthy." When it exits with code 1 (or any non-zero code), Docker marks it as "unhealthy." This status is visible in `docker ps` output and can be used by orchestrators like Docker Swarm or Kubernetes to make decisions about container lifecycle. Common reasons for this error include: the health check endpoint not being ready yet during container startup, incorrect health check command syntax, the target service crashing or becoming unresponsive, or network/DNS issues preventing the health check from reaching the service.

Typical symptoms

• Container shows '(unhealthy)' status in docker ps output
• docker inspect shows Health.Status as 'unhealthy'
• Container keeps restarting when used with depends_on condition: service_healthy
• Docker Compose services fail to start with health check timeout errors
• Orchestrators like Swarm or Kubernetes mark pods/services as unavailable
• Application appears to work but container is marked unhealthy

Common causes

1. Health check command failing because the service inside the container isn't ready yet (missing start-period)
2. Incorrect health check command syntax or wrong endpoint URL
3. Service inside container crashed or is not responding on the expected port
4. Using exec form (brackets) when shell form is needed for pipes or environment variables
5. Timeout value too short for the health check command to complete
6. Missing '|| exit 1' causing non-standard exit codes from tools like curl
7. Health check uses hostname/port only accessible from outside the container
8. Required tools (curl, wget) not installed in the container image

How to fix "health check command returned non-zero exit code: 1"

# View container health status
docker ps

# Get detailed health check information
docker inspect --format='{{json .State.Health}}' <container_name> | jq

# View the last 5 health check results
docker inspect <container_name> | jq '.State.Health.Log[-5:]'

{
  "Status": "unhealthy",
  "FailingStreak": 3,
  "Log": [
    {
      "Start": "2024-01-15T10:00:00.000Z",
      "End": "2024-01-15T10:00:01.000Z",
      "ExitCode": 1,
      "Output": "curl: (7) Failed to connect to localhost port 8080"
    }
  ]
}

# Get a shell in the running container
docker exec -it <container_name> sh

# Run your health check command manually
curl -f http://localhost:8080/health
echo $?  # Check the exit code

docker exec <container_name> curl -f http://localhost:8080/health

HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl -f http://localhost:8080/health || exit 1

services:
  web:
    image: myapp
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      start_period: 60s
      retries: 3

# Correct - shell form
HEALTHCHECK CMD curl -f http://localhost:8080/health || exit 1

# Correct - explicit shell form
HEALTHCHECK CMD ["sh", "-c", "curl -f http://localhost:8080/health || exit 1"]

healthcheck:
  # Shell form (string) - automatically uses shell
  test: curl -f http://localhost:8080/health || exit 1

  # Or CMD-SHELL explicitly
  test: ["CMD-SHELL", "curl -f http://localhost:8080/health || exit 1"]

  # Exec form - no shell, so || won't work
  test: ["CMD", "curl", "-f", "http://localhost:8080/health"]

# Correct - use localhost inside the container
HEALTHCHECK CMD curl -f http://localhost:8080/health || exit 1

# Wrong - container name only works from other containers
HEALTHCHECK CMD curl -f http://myservice:8080/health || exit 1

# Check what ports are listening inside the container
docker exec <container_name> netstat -tlnp
# or
docker exec <container_name> ss -tlnp

# For Debian/Ubuntu
RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*

# For Alpine
RUN apk add --no-cache curl

HEALTHCHECK CMD wget --spider -q http://localhost:8080/health || exit 1

# For images with only basic tools, check if TCP port is open
HEALTHCHECK CMD nc -z localhost 8080 || exit 1

# Or use /dev/tcp in bash
HEALTHCHECK CMD bash -c 'echo > /dev/tcp/localhost/8080' || exit 1

COPY healthcheck.sh /healthcheck.sh
RUN chmod +x /healthcheck.sh
HEALTHCHECK CMD /healthcheck.sh

app.get('/health', (req, res) => {
  // Check database connection, dependencies, etc.
  const isHealthy = checkDependencies();
  if (isHealthy) {
    res.status(200).send('OK');
  } else {
    res.status(503).send('Service Unavailable');
  }
});

@app.route('/health')
def health():
    try:
        # Check dependencies
        db.session.execute('SELECT 1')
        return 'OK', 200
    except Exception:
        return 'Unhealthy', 503

# PostgreSQL
healthcheck:
  test: ["CMD-SHELL", "pg_isready -U postgres"]
  interval: 10s
  timeout: 5s
  retries: 5

# MySQL
healthcheck:
  test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
  interval: 10s
  timeout: 5s
  retries: 5

# Redis
healthcheck:
  test: ["CMD", "redis-cli", "ping"]
  interval: 10s
  timeout: 5s
  retries: 5

Advanced notes

HEALTHCHECK CMD ["sh", "-c", "set -o pipefail && curl -s http://localhost:8080/health | grep -q 'OK' || exit 1"]

services:
  web:
    depends_on:
      db:
        condition: service_healthy
  db:
    healthcheck:
      test: ["CMD-SHELL", "pg_isready"]
      interval: 10s
      timeout: 5s
      retries: 5

Frequently asked questions

What does "health check command returned non-zero exit code: 1" mean?

yml has failed. Docker's health check mechanism periodically runs a command inside your container to verify the service is working correctly. " This status is visible in docker ps output and can be used by orchestrators like Docker Swarm or Kubernetes to make decisions about container lifecycle.

How do I fix "health check command returned non-zero exit code: 1"?

This error occurs when a Docker container's HEALTHCHECK command fails, returning exit code 1 instead of 0. The fix involves debugging the health check command, adjusting timing parameters, and ensuring the target service is properly responding.

What causes "health check command returned non-zero exit code: 1"?

Health check command failing because the service inside the container isn't ready yet (missing start-period) Incorrect health check command syntax or wrong endpoint URL Service inside container crashed or is not responding on the expected port

Is the "health check command returned non-zero exit code: 1" error serious?

It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Related errors

• health check failed

  How to fix 'health check failed' in Docker

  MEDIUM

• OCI runtime exec failed: exec failed: unable to start container process: exec: "curl": executable file not found in $PATH

  How to fix 'executable file not found in $PATH' in Docker healthcheck

  MEDIUM

• Health check failed after maximum retries

  How to fix 'Health check failed after maximum retries' in Docker

  MEDIUM

• Error response from daemon: OCI runtime create failed: runsc error

  How to fix 'OCI runtime create failed: runsc error' in Docker

  HIGH

• WSL 2 requires an update to its kernel component

  How to fix 'WSL 2 requires an update to its kernel component' in Docker

  MEDIUM

• dial tcp: i/o timeout

  How to fix 'dial tcp: i/o timeout' in Docker

  MEDIUM

Official resources & further reading

• 📚Docker Official Documentation
• 📖
  Docker Docs: HEALTHCHECK instruction(Official Docs)
• 💬
  Stack Overflow: Do we really need || exit 1?(Stack Overflow)
• 📝
  Last9: Docker Status Unhealthy - How to Fix It
• 📝
  KhueApps: Fixing healthcheck failed and unhealthy containers
• 📝
  Dev.to: 100 Common Docker Errors & Solutions