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