Docker Container Keeps Crashing and Restarting - How to Fix

Docker Container Keeps Crashing and Restarting - How to Fix

Docker containers crashing and restarting in a loop indicate application or configuration issues. This troubleshooting guide helps you diagnose container crashes, identify root causes, and fix restart loop problems.

For comprehensive container monitoring, see Docker Container Monitoring. For monitoring container resources, see Monitor Docker Container Resource Usage.

Symptoms of Container Crash Restart Loop

• Container status shows "Restarting" repeatedly
• Container logs show repeated error messages
• Container exits with non-zero exit code
• High restart count in container status
• Application fails to start or crashes immediately

Step 1: Check Container Status and Logs

Inspect Container Status

# Check container status
docker ps -a

# Check restart count
docker ps -a --format "table {{.Names}}\t{{.Status}}\t{{.RestartCount}}"

# Get container details
docker inspect <container_name>

# Check container exit code
docker inspect <container_name> | grep -i "exitcode"

Review Container Logs

# View container logs
docker logs <container_name>

# View last 100 log lines
docker logs --tail 100 <container_name>

# Follow logs in real-time
docker logs -f <container_name>

# View logs with timestamps
docker logs -t <container_name>

Step 2: Identify Root Causes

Common Causes of Container Crashes

1. Application Errors:

   • Application crashes on startup
   • Unhandled exceptions
   • Configuration errors
   • Missing dependencies

2. Resource Exhaustion:

   • Memory limits exceeded
   • CPU throttling
   • Disk space full
   • File descriptor limits

3. Configuration Issues:

   • Incorrect environment variables
   • Missing required files
   • Network configuration errors
   • Volume mount issues

4. Health Check Failures:

   • Health check endpoint failing
   • Health check timeout too short
   • Incorrect health check configuration

Step 3: Diagnose Specific Issues

Check Application Logs

# View application logs
docker logs <container_name> 2>&1 | grep -i error

# Check for specific error patterns
docker logs <container_name> | grep -E "error|exception|fatal"

# View logs from crashed container
docker logs <container_name> --since 10m

Check Resource Usage

# Check container resource usage
docker stats <container_name>

# Check memory usage
docker stats <container_name> --no-stream --format "{{.MemUsage}}"

# Check if container is OOM killed
dmesg | grep -i "oom\|killed"

Verify Container Configuration

# Check container environment variables
docker inspect <container_name> | grep -A 20 "Env"

# Check volume mounts
docker inspect <container_name> | grep -A 10 "Mounts"

# Check network configuration
docker inspect <container_name> | grep -A 10 "NetworkSettings"

Step 4: Fix Container Crash Issues

Fix Application Errors

1. Review Application Code:

   • Fix application bugs causing crashes
   • Add proper error handling
   • Fix configuration errors
   • Update application dependencies

2. Update Container Image:

   # Pull latest image
   docker pull <image_name>:latest
   
   # Rebuild container
   docker-compose up -d --force-recreate <service_name>
   

Fix Resource Issues

1. Adjust Resource Limits:

   # Update container with new limits
   docker update --memory="1g" --cpus="2.0" <container_name>
   
   # Or update docker-compose.yml
   # memory: 1g
   # cpus: '2.0'
   

2. Fix Disk Space:

   # Clean up unused resources
   docker system prune -a
   
   # Remove unused volumes
   docker volume prune
   

Fix Configuration Issues

1. Update Environment Variables:

   # Update environment variables
   docker run -e VAR=value <image_name>
   
   # Or update docker-compose.yml
   # environment:
   #   - VAR=value
   

2. Fix Volume Mounts:

   # Verify volume exists
   docker volume ls
   
   # Create volume if missing
   docker volume create <volume_name>
   

Fix Health Check Issues

1. Update Health Check Configuration:

   # docker-compose.yml
   healthcheck:
     test: ["CMD", "curl", "-f", "http://localhost/health"]
     interval: 30s
     timeout: 10s
     retries: 3
     start_period: 40s
   

Step 5: Prevent Future Crashes

Implement Proper Monitoring

Set up automated monitoring with Zuzia.app to track container health continuously:

1. Add Container Health Monitoring:

   docker ps --filter "status=restarting" | wc -l
   

   • Monitor restart count
   • Alert when containers restart frequently

2. Monitor Container Logs:

   docker logs <container_name> 2>&1 | grep -i error | wc -l
   

   • Track error frequency
   • Alert on error spikes

Best Practices

1. Set Appropriate Resource Limits:

   • Configure memory and CPU limits
   • Monitor resource usage
   • Scale containers when needed

2. Implement Health Checks:

   • Configure proper health checks
   • Set appropriate timeouts
   • Monitor health check results

3. Monitor Container Logs:

   • Review logs regularly
   • Set up log aggregation
   • Alert on error patterns

4. Update Containers Regularly:

   • Keep images updated
   • Apply security patches
   • Test updates before production

FAQ: Common Questions About Container Crashes

How do I stop a container from restarting?

Stop a container from restarting by removing the restart policy:

docker update --restart=no <container_name>

How do I debug a container that crashes immediately?

Debug a container by checking logs, running container interactively, and testing application startup manually:

docker run -it <image_name> /bin/bash

How do I prevent containers from restarting on failure?

Configure restart policy to only restart on specific conditions:

docker update --restart=on-failure:3 <container_name>

Can container crashes impact other containers?

Container crashes can impact other containers if they share resources or depend on the crashed container. Monitor container dependencies and implement proper health checks.

Related guides, recipes, and problems

• Related guides

  • Docker Container Monitoring - Production Best Practices and Strategies
  • Kubernetes Monitoring - Container Orchestration Best Practices

• Related recipes

  • How to Monitor Docker Container Resource Usage on Linux Server
  • How to Check Running Docker Containers on Linux Server

• Related problems

  • Service Keeps Stopping and Restarting
  • High Memory Emergency - Find and Kill Memory Hogs