← All writing

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 start or python server.py &, the script exits immediately after launching the subshell daemon. To Docker, PID 1 has terminated, so the container gracefully exits with status 0.
  • If your container executes a task that finishes (e.g., npm run build or echo "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

  1. Find What Process Owns the Host Port: On Linux / macOS:

    sudo lsof -i :8080
    # or
    sudo ss -tulpn | grep 8080
    

    On Windows (PowerShell):

    Get-NetTCPConnection -LocalPort 8080 | Format-Table OwningProcess, State
    
  2. 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>
    
  3. 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

  1. Inspect Disk Usage by Object Type:

    docker system df
    

    Output:

    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%)
    
  2. 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
    
  3. Configure Docker Log Rotation: By default, Docker's json-file logging 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 / CodeUnderlying ProblemPrimary Resolution
Exited (0)PID 1 process finished or ran in backgroundRun daemon in foreground (e.g. daemon off;)
Exit Code 127Executable / shell missing in container imageSwitch bash to sh or install binary
Exit Code 137Process killed by OOM or SIGKILLIncrease container memory allocation
Port already allocatedAnother process occupies host portlsof -i :<port> and terminate conflicting PID
Socket permission deniedUser not in docker groupsudo usermod -aG docker $USER && newgrp docker
No space left on deviceStorage bloated by build cache & volumesdocker system prune -a --volumes