Fix Docker exit code 255 - abnormal container exit from a negative exit code, failed SSH/daemon connection, or fatal startup crash. Step-by-step.
Exit code 255 is the maximum possible exit code value (exit codes are 8-bit unsigned integers, ranging from 0 to 255). When Docker reports "exited with code 255," it means the container's main process terminated abnormally, but the exact cause isn't encoded in the exit code itself. This result commonly comes from a few scenarios: - **Negative exit codes**: When an application exits with a negative value (like -1 in Go, Java, or a shell script), the operating system wraps it to 255 because exit codes must be between 0 and 255. - **SSH failures**: When using Docker Machine or `docker-machine ssh`, connection issues often surface as exit code 255. - **Out-of-range exits**: Calling `exit -1` or similar out-of-range values in shell scripts produces exit code 255. - **Process crashes**: Segmentation faults, memory corruption, or other fatal errors can sometimes produce exit code 255. Unlike more specific exit codes (126 = command found but not executable / permission denied, 127 = command not found, 137 = killed by SIGKILL / OOM), exit code 255 carries no specific meaning and requires deeper investigation through logs and `docker inspect`.
Start by examining the container logs for any error messages:
# Get logs from a running or stopped container
docker logs <container_name_or_id>
# Follow logs in real-time
docker logs -f <container_name_or_id>
# Show timestamps for better debugging
docker logs -t <container_name_or_id>If using docker-compose:
docker-compose logs <service_name>Look for any error messages, stack traces, or warnings that appear before the exit.
The -d (detached) flag can hide errors. Run without it to see output directly:
# Remove -d flag to see output immediately
docker run <image_name>
# Or run interactively for debugging
docker run -it <image_name> /bin/shThis lets you see any errors printed to stdout/stderr before the container exits.
Get detailed information about why the container stopped:
# Inspect container state
docker inspect <container_name_or_id> --format='{{.State.ExitCode}} {{.State.Error}}'
# Get full state information
docker inspect <container_name_or_id> --format='{{json .State}}' | jq
# Check if OOM killed
docker inspect <container_name_or_id> --format='{{.State.OOMKilled}}'The State object may contain additional error information beyond just the exit code.
If your application explicitly exits with a negative code, the OS wraps it to 255. Fix it to use the 0-255 range:
Go example:
// Bad - exits with 255
os.Exit(-1)
// Good - use positive exit codes
os.Exit(1)Shell script example:
# Bad - converts to 255
exit -1
# Good - use 0-255 range
exit 1Python example:
# Bad - may wrap unexpectedly
sys.exit(-1)
# Good - use positive codes
sys.exit(1)If using Docker Machine or seeing SSH-related 255 errors:
# Check Docker Machine status
docker-machine status default
# Regenerate certificates
docker-machine regenerate-certs default
# Restart the machine
docker-machine restart default
# Add SSH key to agent
eval $(ssh-agent -s)
ssh-add ~/.docker/machine/machines/default/id_rsaFor passphrase-protected SSH keys, ensure they're added to the SSH agent before running Docker commands.
Exit code 255 can occur when Docker daemon communication fails:
# Test Docker daemon connectivity
docker info
# Check Docker socket permissions
ls -la /var/run/docker.sock
# Restart Docker service
sudo systemctl restart docker
# Check Docker daemon logs
sudo journalctl -u docker.service -n 50Ensure the Docker daemon is running and your user has permission to access the Docker socket.
If the container exits too quickly to debug, override the entrypoint so you can poke around inside it. The idiomatic form is:
# Drop straight into a shell instead of the image's entrypoint
docker run -it --entrypoint sh <image_name>
# Or keep the container running so you can exec into it from another terminal
docker run -d --entrypoint sleep <image_name> infinity
docker exec -it <container_id> shOnce inside, inspect the filesystem and manually run the original entrypoint to see exactly where it fails:
/path/to/original/entrypoint.shExit code mapping: Exit codes in Unix/Linux are 8-bit unsigned integers (0-255). Negative exit codes wrap around: -1 becomes 255, -2 becomes 254, etc. This is because the kernel stores the value as exit_code & 0xFF.
Docker-in-Docker (dind) issues: When running Docker inside Docker, exit code 255 often indicates problems with the inner Docker daemon. Ensure proper socket mounting or use the docker:dind image with appropriate configuration.
Kubernetes debugging: In K8s, if pods exit with code 255:
# Temporarily override for debugging
command: ["sleep", "infinity"]Then use kubectl exec to investigate.
Signal handling: Some signals can't be caught by applications. If a process receives an uncatchable signal in an unusual state, it may exit with 255. Use dmesg on the host to check for kernel-level process termination.
Memory issues: While OOM typically produces exit code 137, severe memory corruption can sometimes result in exit code 255. Check docker inspect for OOMKilled status and monitor container memory usage.
Restart policies: A restart policy fires on *every* exit, including an immediate exit 255. --restart=on-failure:N will restart a container that instantly exits 255 (up to N attempts), and --restart=always/unless-stopped will keep restarting it:
docker run --restart=on-failure:5 <image_name>The 10-second figure that's often misquoted relates to backoff, not a precondition for restarting: Docker uses an exponentially increasing delay between restart attempts (capped), and the *backoff counter is reset* once a container stays up long enough. It does not mean a container must survive 10 seconds before the policy applies.
Container exited with code 128: invalid exit argument
How to fix 'Container exited with code 128' in Docker
Error response from daemon: Get https://registry-1.docker.io/v2/: Proxy Authentication Required
How to fix 'Proxy Authentication Required' in Docker
error exporting cache: failed to export cache
How to fix 'error exporting cache: failed to export cache' in Docker
net/http: TLS handshake timeout
How to fix 'net/http: TLS handshake timeout' in Docker
Read-only file system
How to fix 'Read-only file system' in Docker