How to fix Docker container exited with code 255 in Docker

DockerINTERMEDIATEMEDIUMUpdated Sep 17, 2026· 685 views

Fix Docker exit code 255 - abnormal container exit from a negative exit code, failed SSH/daemon connection, or fatal startup crash. Step-by-step.

Quick fix

Fixes Docker container exited with code 255

# 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>
  1. Check container logs for error details
  2. Run container without detached mode for immediate output
  3. Inspect the container's exit details
  4. Check for negative exit codes in your application
docker — error
# 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>
Docker container exited with code 255

What this error means

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`.

Typical symptoms

  • Container exits immediately with 'Exited (255)' status
  • docker-compose shows 'exited with code 255' without additional details
  • docker logs shows no clear error message before termination
  • Container runs fine locally but fails in CI/CD environments
  • SSH-related Docker commands fail with 'exit status 255'
  • Container restarts repeatedly with exit code 255
  • docker exec returns exit status 255 without error output
  • Application exits with negative return code showing as 255

Common causes

  1. Application exits with a negative exit code (e.g., exit(-1) wraps to 255)
  2. SSH connection failures in Docker Machine or docker-machine ssh
  3. Docker daemon communication issues or socket problems
  4. Process killed by a signal that couldn't be properly handled
  5. TTY/pseudo-terminal allocation problems with docker exec
  6. Corrupted shared memory or segmentation fault in the containerized process
  7. Docker-in-docker (dind) execution failures
  8. VirtualBox or hypervisor configuration issues with Docker Toolbox
  9. Entrypoint script returning a non-standard exit code
  10. Network connectivity issues causing the process to fail

How to fix "Docker container exited with code 255"

1Check container logs for error details

Start by examining the container logs for any error messages:

bash
# 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:

bash
docker-compose logs <service_name>

Look for any error messages, stack traces, or warnings that appear before the exit.

2Run container without detached mode for immediate output

The -d (detached) flag can hide errors. Run without it to see output directly:

bash
# Remove -d flag to see output immediately
docker run <image_name>

# Or run interactively for debugging
docker run -it <image_name> /bin/sh

This lets you see any errors printed to stdout/stderr before the container exits.

3Inspect the container's exit details

Get detailed information about why the container stopped:

bash
# 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.

4Check for negative exit codes in your application

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:

go
// Bad - exits with 255
os.Exit(-1)

// Good - use positive exit codes
os.Exit(1)

Shell script example:

bash
# Bad - converts to 255
exit -1

# Good - use 0-255 range
exit 1

Python example:

python
# Bad - may wrap unexpectedly
sys.exit(-1)

# Good - use positive codes
sys.exit(1)
5Debug SSH-related exit code 255 errors

If using Docker Machine or seeing SSH-related 255 errors:

bash
# 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_rsa

For passphrase-protected SSH keys, ensure they're added to the SSH agent before running Docker commands.

6Check Docker daemon connectivity

Exit code 255 can occur when Docker daemon communication fails:

bash
# 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 50

Ensure the Docker daemon is running and your user has permission to access the Docker socket.

7Override the entrypoint to keep the container alive

If the container exits too quickly to debug, override the entrypoint so you can poke around inside it. The idiomatic form is:

bash
# 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> sh

Once inside, inspect the filesystem and manually run the original entrypoint to see exactly where it fails:

bash
/path/to/original/entrypoint.sh

Advanced notes

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 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:

yaml
# 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:

bash
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.

Frequently asked questions

What does "Docker container exited with code 255" mean?
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.
How do I fix "Docker container exited with code 255"?
Fix Docker exit code 255 - abnormal container exit from a negative exit code, failed SSH/daemon connection, or fatal startup crash. Step-by-step.
What causes "Docker container exited with code 255"?
Application exits with a negative exit code (e.g., exit(-1) wraps to 255) SSH connection failures in Docker Machine or docker-machine ssh Docker daemon communication issues or socket problems
Is the "Docker container exited with code 255" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading