Exit code 255 is a generic error code indicating an abnormal container termination. It typically occurs when a process exits with a negative exit code (which gets converted to 255), when SSH connections fail, or when Docker encounters an unspecified fatal error.
Exit code 255 is the maximum possible exit code value (since 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 specified by the exit code itself. This error commonly occurs in several scenarios: - **Negative exit codes**: When an application exits with a negative value (like -1 in Go or Java), the operating system converts 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 manifest as exit code 255. - **Out-of-range exits**: Using `exit -1` or similar out-of-range values in shell scripts results in 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 = permission denied, 127 = command not found, 137 = OOM killed), exit code 255 requires deeper investigation through logs and debugging.
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, fix it:
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 cause issues
sys.exit(-1)
# Good - use positive codes
sys.exit(1)Some exit code 255 issues relate to permissions or security restrictions. Test with privileged mode:
# WARNING: Only use for debugging, not production
docker run --privileged <image_name>If this resolves the issue, the problem is likely related to:
- Security contexts (SELinux, AppArmor)
- Capability restrictions
- Device access permissions
Identify the specific capability needed rather than running privileged in production.
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:
# Start with sleep to keep container alive
docker run -it --entrypoint /bin/sh <image_name> -c "sleep infinity"
# Then exec into the running container
docker exec -it <container_id> /bin/sh
# Manually run the original entrypoint to see errors
/path/to/original/entrypoint.shThis allows you to inspect the container's filesystem and manually run commands to identify the failure point.
Exit 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 uses exit_code & 0xFF to store the value.
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 modify 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: Docker's restart policy only takes effect after a container runs successfully for at least 10 seconds. Containers that immediately exit with 255 may not be automatically restarted as expected:
docker run --restart=on-failure:5 <image_name>image operating system "linux" cannot be used on this platform
How to fix 'image operating system linux cannot be used on this platform' in Docker
manifest unknown: manifest unknown
How to fix 'manifest unknown' in Docker
cannot open '/etc/passwd': Permission denied
How to fix 'cannot open: Permission denied' in Docker
Error response from daemon: failed to create the ipvlan port
How to fix 'failed to create the ipvlan port' in Docker
toomanyrequests: Rate exceeded for anonymous users
How to fix 'Rate exceeded for anonymous users' in Docker Hub