Docker Container Keeps Restarting: Diagnosis and Fix Guide
If docker ps shows your container in a perpetual restart loop, here's the systematic way to diagnose and fix it.
Step 1: Read the Crash Logs First
docker logs my-container --tail 100
docker logs my-container --tail 100 2>&1 | grep -i "error\|fatal\|exit\|killed"
This is where 80% of your answers are. Don't skip this.
Step 2: Check the Exit Code
docker inspect my-container --format='{{.State.ExitCode}}'
| Exit Code | Meaning | Action |
|---|---|---|
| 0 | Clean exit (your CMD finished) | Fix your entrypoint to keep running |
| 1 | Application error | Check logs for error |
| 137 | OOM Killed (SIGKILL) | Increase memory limit |
| 139 | Segfault | Binary/library issue |
| 143 | SIGTERM | External kill signal |
Step 3: Stop the Restart Loop
docker update --restart=no my-container
Now you can investigate without the container fighting you.
Step 4: Fix by Exit Code
Exit Code 137 (OOM Killed)
# Check current memory usage
docker stats my-container --no-stream
# Increase memory limit
docker run --memory=512m --memory-swap=512m myimage
# In docker-compose.yml
services:
myapp:
deploy:
resources:
limits:
memory: 512M
Exit Code 1 (Application Error)
Common causes and fixes:
# 1. Missing environment variable
docker run -e DATABASE_URL=postgres://... myimage
# 2. Can't connect to database (wrong hostname)
# In docker-compose, use service name, not localhost
DATABASE_URL=postgres://db:5432/mydb # 'db' = service name
# 3. Port already in use
lsof -i :3000 # Find what's using the port
docker run -p 3001:3000 myimage # Map to different host port
Container Exits With Code 0 (Clean Exit)
Your process ran and finished. Docker restarts it because of your restart policy.
# BAD — this runs and exits
CMD ["node", "migrate.js"]
# GOOD — this keeps running
CMD ["node", "server.js"]
Or if running a script:
CMD ["sh", "-c", "node migrate.js && node server.js"]
Step 5: Debug Interactively
# Override entrypoint to get a shell
docker run -it --entrypoint /bin/sh myimage
# Or exec into a running container
docker exec -it my-container /bin/bash
# Inside container — test connectivity
curl -I http://db:5432 # Can it reach the DB?
env | grep DATABASE # Are env vars set?
Step 6: Check Docker Compose Dependencies
services:
app:
image: myapp
depends_on:
db:
condition: service_healthy # Wait for DB to be ready
db:
image: postgres:15
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 5s
timeout: 5s
retries: 5
Without depends_on with health checks, your app starts before the DB is ready → connection refused → crash → restart loop.
Full Diagnostic Checklist
# 1. Get recent logs
docker logs my-container --tail 50 2>&1
# 2. Get exit code
docker inspect my-container | grep '"ExitCode"'
# 3. Check resource usage
docker stats --no-stream
# 4. Inspect full config
docker inspect my-container | python3 -m json.tool
# 5. Check events
docker events --filter container=my-container --since 10m
Restart loops at 2AM are brutal. Step2Dev — paste your docker logs and get the exact fix for your container setup in 60 seconds.