How to Fix Docker Container Restart Loops

What Is a Restart Loop?

A Docker container stuck in a restart loop continuously crashes and restarts, often cycling through "Restarting" status. This is typically caused by application errors, misconfiguration, or resource constraints on your Breeze.

Step 1: Identify the Looping Container

# List containers with their restart counts
docker ps -a --format "table {{.Names}}\t{{.Status}}\t{{.RunningFor}}"

# Watch for containers with high restart counts
docker inspect --format='{{.Name}} {{.RestartCount}}' $(docker ps -aq) | sort -t' ' -k2 -nr | head -10

Step 2: Check Container Logs

# View recent logs
docker logs --tail 100 container_name

# Follow logs in real time
docker logs -f container_name

# Show timestamps
docker logs --tail 50 -t container_name

Step 3: Stop the Restart Loop

Prevent the container from restarting while you debug:

docker update --restart=no container_name
docker stop container_name

Step 4: Debug Interactively

Start the container without the normal entrypoint to inspect its state:

# Override entrypoint to get a shell
docker run -it --entrypoint /bin/sh image_name

# Or with bash if available
docker run -it --entrypoint /bin/bash image_name

Common Causes and Fixes

Missing Environment Variables

# Check what env vars the container expects
docker inspect container_name | grep -A 20 "Env"

# Ensure all required variables are set in docker-compose.yml or .env file

Port Conflicts

# Check if another process uses the same port
ss -tlnp | grep :8080

# Change the host port mapping in docker-compose.yml
ports:
  - "8081:8080"

Health Check Failures

# Check health status
docker inspect --format='{{json .State.Health}}' container_name | jq .

# Temporarily disable health check to test
docker run --no-healthcheck image_name

Out of Memory

# Check if container was OOM killed
docker inspect container_name | grep -i oom

# Increase memory limit
docker update --memory=512m container_name

Prevention

• Always check logs before restarting a failed container
• Use restart: unless-stopped instead of restart: always
• Set resource limits to prevent runaway containers
• Implement proper health checks that match your application startup time