Docker Container Failures

Docker Container Failures

Docker container failures fall into two categories: containers that fail to start (image issues, missing environment variables, port conflicts) and containers that start but crash or misbehave at runtime (application errors, resource exhaustion, external dependencies). The diagnostic approach is the same for both: read the logs, inspect the container state, and trace the failure back to its root cause before restarting the container.

Container failure states

Application crash diagnosis

# Container keeps restarting — always check PREVIOUS logs (from crashed container):
docker ps -a    # See containers including exited ones
docker logs --previous mycontainer    # Logs from the LAST run before this restart

# Check exit code and OOM status:
docker inspect mycontainer | python3 -c "
import json, sys
d = json.load(sys.stdin)[0]
s = d['State']
print('Status:', s['Status'])
print('ExitCode:', s['ExitCode'])
print('OOMKilled:', s['OOMKilled'])
print('Error:', s.get('Error', 'none'))
"

docker inspect State output

Status: exited
ExitCode: 137
OOMKilled: true
Error: none
# OOMKilled: true = container exceeded its memory limit
# Fix: increase memory limit in docker run or docker-compose.yml

# Look at recent crash logs:
docker logs mycontainer --tail 50 --since "1h"
docker events --filter container=mycontainer    # Container lifecycle events

Container startup failures

# Container exits immediately — debug by running with a shell:
docker run --rm -it --entrypoint /bin/sh myimage:latest
# Now you can inspect the filesystem and test commands manually

# Check environment variables are set correctly:
docker run --rm myimage:latest env | sort
# Compare required variables with what is provided

# Port conflict — container cannot bind to port already in use:
docker logs mycontainer

Port conflict error in container log

Error starting userland proxy: listen tcp4 0.0.0.0:80: bind: address already in use
# Fix: find what is using port 80 on the host:
sudo ss -tlnp | grep :80
# Then either stop that service or use a different host port:
# docker run -p 8080:80 nginx  (map host 8080 to container 80)

Runtime failures and resource issues

# Container running but performance degraded:
docker stats mycontainer    # Live CPU, memory, network, block I/O

# Container hitting memory limit (throttled):
docker stats --no-stream mycontainer

docker stats output near memory limit

CONTAINER   CPU %   MEM USAGE / LIMIT     MEM %    NET I/O
myapp       45.2%   498MiB / 512MiB       97.3%    125MB / 45MB
# Memory at 97% of limit → likely being throttled or close to OOM kill
# Fix: increase memory limit

# Update memory limit without recreating container (docker-compose):
# In docker-compose.yml:
# deploy:
#   resources:
#     limits:
#       memory: 1G    # Increase from 512M to 1G

# Apply:
docker compose up -d myapp    # Recreates only myapp container with new settings

# Check container filesystem usage (common with log files inside containers):
docker exec mycontainer df -h    # Disk usage inside container

Conclusion

Always check docker logs --previous for containers that restart in a loop — the current logs often show only the startup messages, while the previous logs contain the actual error that caused the crash. For OOM-killed containers (OOMKilled: true), the logs may show nothing unusual because the kernel kills the process abruptly before it can write a final error message. In this case, the only indicator is the 137 exit code and the OOMKilled field in docker inspect.