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.
DE
Source
This article was originally published by DEV Community and written by Yash.
Read original article on DEV Community