Understanding Docker exit code 255 - an unknown or unspecified error occurred in the container, often related to SSH or runtime failures.

Learn how to resolve Docker Exit Code 255 - Unknown Error. Understanding Docker exit code 255 - an unknown or unspecified error occurred in the container, often related to SSH or runtime failures.

Docker Exit Code 255 - Unknown Error

What It Means

Docker exit code 255 indicates an unknown or unspecified error. This exit code is not standardized and can mean different things depending on the context. It often appears with SSH-related operations, runtime initialization failures, or when the exit code overflows (codes wrap modulo 256, so -1 becomes 255).

Common Causes

SSH connection failure inside the container
Runtime initialization error (JVM, Python interpreter)
Exit code overflow (-1 or values > 255 wrap to 255)
Entrypoint script exiting without a specific code
Container runtime errors during process setup
Invalid or corrupted executable
Missing shared libraries at startup
Docker healthcheck failures with ambiguous exit codes

How to Fix

Check container logs for the actual error

# The real error message is usually in the logs
docker logs <container-id> 2>&1

# Check Docker events
docker events --since "30m" --filter "container=<container-id>"

# Inspect the container state
docker inspect <container-id> --format='{{json .State}}'

Debug interactively

# Override the entrypoint to get a shell
docker run -it --entrypoint /bin/sh my-image

# Check if the binary runs
/app/my-binary --version

# Check for missing libraries
ldd /app/my-binary

# Check environment
env

# SSH returns 255 on connection failure
# Inside a container:
ssh user@host  # Returns 255 if connection fails

# Fix: check SSH configuration
ssh -v user@host  # Verbose output shows the issue

# Common fixes:
# - Ensure SSH keys are properly mounted
# - Check network connectivity
# - Verify host key configuration
docker run -v ~/.ssh:/root/.ssh:ro my-image ssh user@host

Fix missing shared libraries

# Check what's missing
# docker run --rm my-image ldd /app/my-binary

# Install missing libraries
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y \
    libssl3 \
    libcurl4 \
    && rm -rf /var/lib/apt/lists/*

COPY my-binary /app/my-binary
CMD ["/app/my-binary"]

Fix exit code overflow

# Some programs return -1 on error, which becomes 255
# In your scripts, use explicit exit codes:

#!/bin/bash
if ! command_that_might_fail; then
  echo "Command failed" >&2
  exit 1  # Use explicit code instead of relying on the command's exit code
fi

Fix JVM startup issues

# Ensure JVM has enough memory and correct settings
FROM eclipse-temurin:21-jre-alpine

# Set JVM options
ENV JAVA_OPTS="-Xms256m -Xmx512m"
CMD ["sh", "-c", "java $JAVA_OPTS -jar /app/app.jar"]

Fix Python runtime issues

# Ensure Python can find its modules
FROM python:3.12-slim
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "app.py"]

Docker Exit Code 1 - General error: A more common application-level failure.
Docker Exit Code 125 - Docker daemon error: Docker itself failed.
Docker Exit Code 137 - SIGKILL: Container was killed (OOM or forced).