Docker Container Not Starting — Troubleshooting Guide (2026)

Symptom: docker run exits immediately, container keeps restarting, or health check fails.

Step 1: Check Container Logs First

# View logs from the last failed run
docker logs container_name

# Follow logs in real time
docker logs -f container_name

# Last 50 lines
docker logs --tail 50 container_name

# Logs with timestamps
docker logs -t container_name

# For a container that exited immediately:
docker logs $(docker ps -lq)  # Most recently exited container

Step 2: Check Exit Code

docker ps -a  # Shows all containers including stopped ones
# Look at STATUS column: "Exited (1)" or "Exited (137)"

# Exit codes:
# 0  - Clean exit (intentional stop)
# 1  - Application error (check logs)
# 125 - Docker daemon error
# 126 - Container command not executable
# 127 - Container command not found
# 137 - Killed (OOM or docker stop/kill)
# 139 - Segfault
# 143 - SIGTERM received (graceful stop)

Step 3: Run Interactively to Debug

# Override the CMD and get a shell to investigate
docker run -it --entrypoint /bin/sh image_name
# OR for images with bash:
docker run -it --entrypoint /bin/bash image_name

# If container starts but crashes fast, override CMD:
docker run -it image_name sh -c "echo test && ls -la /app"

# Run with environment variables from a file:
docker run -it --env-file .env image_name sh

Common Error 1: Port Already in Use

# Error: "bind: address already in use"
docker run -p 80:80 nginx
# Error response: driver failed ... address already in use

# Fix: Find what's using the port
lsof -i :80
# OR:
ss -tlnp | grep :80

# Kill the process or use a different port:
docker run -p 8080:80 nginx

Common Error 2: Volume Mount Issues

# Error: "no such file or directory" or permission denied

# Check your volume path exists:
ls -la /path/to/host/directory

# Fix: Create directory first
mkdir -p /path/to/host/directory
docker run -v /path/to/host/directory:/app/data myimage

# Fix: Permissions (common on Linux)
chmod 755 /path/to/host/directory
# OR run container as specific user:
docker run --user $(id -u):$(id -g) -v $(pwd):/app myimage

Common Error 3: Missing Environment Variables

# Application crashes because DATABASE_URL not set
# Check what env vars are set in the container:
docker run --env-file .env myimage env | grep DATABASE

# Dockerfile: set sensible defaults
ENV DATABASE_URL=postgres://localhost:5432/mydb
ENV PORT=5000

# docker-compose.yml:
services:
  app:
    env_file:
      - .env
    environment:
      - NODE_ENV=production

Common Error 4: Out of Memory (OOM Kill)

# Exit code 137 = OOM kill
# Check docker stats:
docker stats container_name

# Check system memory:
free -h

# Fix: Increase memory limit or optimize app
docker run --memory=512m --memory-swap=1g myimage

# In docker-compose.yml:
services:
  app:
    deploy:
      resources:
        limits:
          memory: 512M

Common Error 5: Health Check Failure

# Container shows "unhealthy" or keeps restarting
docker inspect container_name | grep -A 20 '"Health"'

# Check your Dockerfile health check:
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3   CMD curl -f http://localhost:8080/health || exit 1

# Temporarily disable health check to debug:
docker run --no-healthcheck myimage

# Debug health check manually:
docker exec container_name curl -v http://localhost:8080/health

Common Error 6: Image Build Issues

# Rebuild without cache when dependencies change
docker build --no-cache -t myimage .

# Multi-stage build — common mistake: wrong stage
# Check your Dockerfile FROM stages
FROM node:20-alpine AS builder
# ... build steps

FROM node:20-alpine AS production  # ← make sure you're running this stage
COPY --from=builder /app/dist ./dist

# Build specific stage:
docker build --target production -t myimage .

Systematic Troubleshooting Script

#!/bin/bash
# Quick Docker debug script
CONTAINER=$1

echo "=== Container Status ==="
docker ps -a | grep $CONTAINER

echo "=== Last 50 Log Lines ==="
docker logs --tail 50 $CONTAINER

echo "=== Container Inspect (relevant sections) ==="
docker inspect $CONTAINER | python3 -c "
import sys, json
d = json.load(sys.stdin)[0]
state = d['State']
print('Status:', state['Status'])
print('ExitCode:', state['ExitCode'])
print('Error:', state['Error'])
print('OOMKilled:', state['OOMKilled'])
"

echo "=== Resource Usage ==="
docker stats --no-stream $CONTAINER

docker-compose Specific Issues

# Service dependency ordering
services:
  app:
    depends_on:
      db:
        condition: service_healthy  # Wait for DB health check to pass
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

# Restart logs after compose down/up:
docker-compose down && docker-compose up --build

# View logs for specific service:
docker-compose logs -f app