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

# 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