Famous Docker Errors & Production Fixes: Container Exit Codes, Port Conflicts & Storage Exhaustion
· Sourabh G Kulkarni
Demystify common Docker runtime errors: exit codes 127 and 139, port binding conflicts, daemon socket permissions, and storage exhaustion with CLI fixes.
Before software reaches a Kubernetes cluster, it lives on a developer's workstation or a CI runner inside Docker. And while containerization promises to eliminate "it works on my machine", Docker introduces its own suite of deceptive failure modes.
Containers that exit immediately after starting, silent daemon socket permission rejections, mysterious bind: address already in use errors, and sudden no space left on device failures are everyday hurdles for DevOps and platform engineers.
Here is a practical, field-tested guide to diagnosing and fixing the most notorious Docker production errors.
1. Container Exits Immediately (Exit Code 0 vs Exit Code 1)
One of the most frustrating experiences for engineers new to Docker is running docker run -d my-image, followed by docker ps, and seeing nothing running.
A check with docker ps -a reveals:
CONTAINER ID IMAGE STATUS PORTS NAMES
8d3f1a2c9b4e my-app:v1 Exited (0) 2 seconds ago festive_curie
The Underlying Mechanics
A Docker container is not an operating system or a full virtual machine; it is an isolated process on the host kernel. A container only runs for as long as its primary foreground process (PID 1) remains active.
- If your container executes a background script like
service nginx startorpython server.py &, the script exits immediately after launching the subshell daemon. To Docker, PID 1 has terminated, so the container gracefully exits with status0. - If your container executes a task that finishes (e.g.,
npm run buildorecho "Done"), it finishes its job and shuts down.
The Fix
Ensure your container's entrypoint or command executes a process in the foreground:
# ❌ INCORRECT: Forks into the background; container exits immediately
CMD service nginx start
# ✅ CORRECT: Runs Nginx in the foreground as PID 1
CMD ["nginx", "-g", "daemon off;"]
For Node.js or Python services, avoid backgrounding:
# ✅ CORRECT
CMD ["node", "dist/server.js"]
2. Port Binding Conflicts: bind: address already in use
When starting a container with published ports, Docker throws:
Error response from daemon: driver failed programming external connectivity on endpoint web-app:
Bind for 0.0.0.0:8080 failed: port is already allocated.
The Diagnostic Workflow
-
Find What Process Owns the Host Port: On Linux / macOS:
sudo lsof -i :8080 # or sudo ss -tulpn | grep 8080On Windows (PowerShell):
Get-NetTCPConnection -LocalPort 8080 | Format-Table OwningProcess, State -
Check for Zombie Docker Containers: Often, an earlier orphaned container is still holding onto the port:
docker ps --filter "publish=8080"Kill and remove it:
docker rm -f <container_id> -
Dynamic Host Port Allocation: If you run automated integration test suites concurrently, avoid hardcoding host ports. Instead, publish to a random ephemeral port:
docker run -d -p :8080 my-image # Query the randomly assigned host port: docker port <container_id> 8080
3. Storage Exhaustion: no space left on device
Docker does not automatically prune unused layers, stopped containers, build caches, or dangling volumes. Over weeks of daily builds, your host's root partition (/var/lib/docker) quietly accumulates dozens of gigabytes of orphaned data.
The Cleanup Hierarchy
-
Inspect Disk Usage by Object Type:
docker system dfOutput:
TYPE TOTAL ACTIVE SIZE RECLAIMABLE Images 48 12 32.4GB 24.1GB (74%) Containers 34 4 1.8GB 1.5GB (83%) Local Volumes 18 2 14.2GB 12.6GB (88%) Build Cache 212 0 18.5GB 18.5GB (100%) -
Prune Dangling Build Cache and Stopped Containers:
# Safe prune: Removes stopped containers, unused networks, and dangling images docker system prune -f # Deep prune: Also purges BuildKit cache and unused volume mounts docker builder prune -a -f docker volume prune -f -
Configure Docker Log Rotation: By default, Docker's
json-filelogging driver stores container logs on disk indefinitely without a size cap. Configure a global cap in/etc/docker/daemon.json:{ "log-driver": "json-file", "log-opts": { "max-size": "50m", "max-file": "3" } }
4. Permission Denied on /var/run/docker.sock
When running any docker CLI command on Linux:
permission denied while trying to connect to the Docker daemon socket at
unix:///var/run/docker.sock: Get "http://%2Fvar%2Frun%2Fdocker.sock/v1.24/version": dial unix /var/run/docker.sock: connect: permission denied
The Underlying Mechanics
The Docker daemon (dockerd) runs as root. Communication between the docker client CLI and the daemon happens over the Unix domain socket /var/run/docker.sock, which is owned by the root user and the docker group.
The Fix
Do not run all your commands with sudo docker. Instead, add your current user account to the docker system group:
# 1. Create the docker group if it doesn't already exist
sudo groupadd docker
# 2. Add your active user to the docker group
sudo usermod -aG docker $USER
# 3. Apply group changes to current shell session
newgrp docker
# 4. Verify without sudo
docker ps
5. Exit Code 127: Command Not Found Inside Minimal Images
When your container exits with code 127:
docker: Error response from daemon: failed to create task for container:
failed to create shim task: OCI runtime create failed: runc create failed:
unable to start container process: exec: "bash": executable file not found in $PATH: unknown.
The Cause
Modern security and performance best practices favor minimal base images like Alpine Linux (alpine) or Distroless (gcr.io/distroless/static). These ultra-small images strip out GNU utilities, package managers, and often lack /bin/bash.
If your CMD or ENTRYPOINT hardcodes ["bash", "-c", "..."], the kernel fails to locate the bash interpreter, returning Unix exit code 127.
The Fix
Use the POSIX-compliant standard shell /bin/sh or execute the application binary directly in exec-form:
# ❌ Fails on Alpine (bash not installed by default)
CMD ["bash", "entrypoint.sh"]
# ✅ Works on all Linux containers (POSIX shell)
CMD ["sh", "entrypoint.sh"]
# 🚀 Best Practice: Exec form without any shell overhead
CMD ["./server"]
Summary Reference Table
| Error Message / Code | Underlying Problem | Primary Resolution |
|---|---|---|
| Exited (0) | PID 1 process finished or ran in background | Run daemon in foreground (e.g. daemon off;) |
| Exit Code 127 | Executable / shell missing in container image | Switch bash to sh or install binary |
| Exit Code 137 | Process killed by OOM or SIGKILL | Increase container memory allocation |
| Port already allocated | Another process occupies host port | lsof -i :<port> and terminate conflicting PID |
| Socket permission denied | User not in docker group | sudo usermod -aG docker $USER && newgrp docker |
| No space left on device | Storage bloated by build cache & volumes | docker system prune -a --volumes |