How to fix Container exited with code 128: invalid exit argument in Docker

DockerINTERMEDIATEMEDIUM

Exit code 128 indicates an invalid exit argument or is the base value for signal-related container terminations. This error commonly occurs due to Git/SSH authentication failures during builds, invalid exit() arguments in scripts, volume mount issues, or OCI runtime errors.

What this error means

Exit code 128 in Docker can have multiple meanings depending on the context: **1. Invalid exit argument**: In bash and POSIX shells, exit code 128 means "Invalid argument to exit." This occurs when a script calls `exit` with a non-integer argument (like `exit 3.14` or `exit "error"`) or a value outside the valid 0-255 range. **2. Base value for signal exits**: Exit codes in the 128+n range indicate the container was terminated by a signal, where n is the signal number. For example, exit code 137 (128+9) means SIGKILL, and 143 (128+15) means SIGTERM. A pure 128 exit code without signal offset typically indicates a startup failure before signals could be processed. **3. Git operation failures**: Exit code 128 is commonly associated with Git errors, particularly authentication failures when cloning repositories during Docker builds. This happens when SSH keys aren't available or Git credentials are missing. **4. OCI runtime errors**: The container runtime may return 128 when it cannot properly initialize or start the container due to configuration issues, missing dependencies, or permission problems.

How to fix "Container exited with code 128: invalid exit argument"

1Check container logs for detailed error messages

First, examine the container logs to identify the root cause:

bash

# View logs for a stopped container
docker logs <container_name_or_id>

# For more context, inspect the container state
docker inspect <container_name_or_id> --format='{{.State.ExitCode}} {{.State.Error}}'

Look for specific error messages like "Permission denied", "Host key verification failed", or "repository not found".

2Fix Git authentication issues in Docker builds

If exit code 128 occurs during git clone in a Dockerfile, ensure proper SSH or HTTPS authentication:

dockerfile

# Option 1: Use BuildKit SSH forwarding
# syntax=docker/dockerfile:1
FROM alpine
RUN apk add --no-cache git openssh-client
RUN --mount=type=ssh git clone [email protected]:user/repo.git

Build with SSH agent forwarding:

bash

DOCKER_BUILDKIT=1 docker build --ssh default .

Or use HTTPS with a personal access token:

dockerfile

ARG GITHUB_TOKEN
RUN git clone https://${GITHUB_TOKEN}@github.com/user/repo.git

3Validate exit command arguments in scripts

Ensure all exit calls in your scripts use valid integer arguments (0-255):

bash

# Incorrect - will cause exit code 128
exit "error"
exit 3.14
exit $undefined_variable  # if unset, may expand to invalid value

# Correct usage
exit 0   # Success
exit 1   # Generic error
exit 2   # Misuse of command

To debug, add set -x at the start of your script to trace execution and identify the failing exit call.

4Handle volume mount timing issues

If containers exit with code 128 after system reboot, network volumes may not be ready:

yaml

# docker-compose.yml - add healthcheck and depends_on
services:
  app:
    image: myapp
    depends_on:
      volume-service:
        condition: service_healthy
    restart: on-failure:5
    
  volume-service:
    image: volume-checker
    healthcheck:
      test: ["CMD", "test", "-d", "/mnt/data"]
      interval: 5s
      timeout: 3s
      retries: 10

Alternatively, add a startup script that waits for volumes:

bash

#!/bin/sh
until [ -d "/mnt/data" ]; do
  echo "Waiting for volume..."
  sleep 2
done
exec "$@"

5Fix Git directory ownership issues

Git may refuse to operate if the directory owner differs from the current user (common with volume mounts):

bash

# Inside the container, add the directory to Git's safe list
git config --global --add safe.directory /app

# Or in your Dockerfile
RUN git config --global --add safe.directory '*'

This is especially common when running as root but the volume was created by another user.

6Resolve OCI runtime errors

For OCI runtime failures with exit code 128, check Docker daemon logs:

bash

# View Docker daemon logs
sudo journalctl -u docker.service -n 50

# Check for containerd issues
sudo journalctl -u containerd.service -n 50

Common fixes:

bash

# Restart Docker daemon
sudo systemctl restart docker

# Update containerd and runc
sudo apt update && sudo apt upgrade containerd.io

# Clear potentially corrupted container state
docker system prune -f

7Debug container startup failures

If the container fails too quickly to debug, override the entrypoint:

bash

# Run with shell to inspect the environment
docker run -it --entrypoint /bin/sh <image_name>

# Check if the original command exists and is executable
which <original_command>
ls -la /app/entrypoint.sh

# Test running the command manually
/app/entrypoint.sh

For docker-compose, use:

yaml

services:
  myapp:
    entrypoint: ["sleep", "infinity"]

Then exec into the container to debug.

How to fix Container exited with code 128: invalid exit argument in Docker

What this error means

Typical symptoms

Common causes

How to fix "Container exited with code 128: invalid exit argument"

Advanced notes

Related errors

Official resources & further reading