Decoding Container Exit Codes: What They Mean and How to Troubleshoot Them

What Is a Container Exit Code

When a container stops, the container engine reports an exit code that indicates why the container terminated. For Kubernetes users, container failures are a common cause of pod anomalies, and understanding exit codes helps pinpoint the root cause during troubleshooting.

0 – Normal exit: developer signals successful completion.

1 – Application error: caused by a programming mistake or an invalid reference in the image spec.

125 – Container failed to run: docker run did not execute successfully.

126 – Command invocation error: the specified command could not be called.

127 – File or directory not found: the referenced file does not exist in the image.

128 – Invalid parameter for exit: an out‑of‑range exit value was used.

134 – Abnormal termination (SIGABRT): the container called abort() or triggered an assertion.

137 – Immediate termination (SIGKILL): the OS killed the container.

139 – Segmentation fault (SIGSEGV): illegal memory access.

143 – Graceful termination (SIGTERM): container stopped normally after a termination signal.

255 – Exit status out of range: the entrypoint exited with an unknown reason.

The following sections explain how to troubleshoot failing containers on the host and in Kubernetes, with detailed guidance for each exit code.

Container Lifecycle

To better understand why a container fails, first review its lifecycle. In Docker, a container can be in one of several states:

Created : The container has been created but not started yet (after docker create).

Up : The container is currently running (after docker start or docker run).

Paused : The container process is running but Docker has paused it (e.g., after docker pause).

Exited : The container has stopped, usually because its main process was killed.

When a container reaches the Exited state, Docker logs an exit code that tells you what caused the termination.

Understanding Container Exit Codes

Below is a deeper look at each exit code, its meaning, typical causes, and recommended remediation steps.

Exit Code 0: Normal Exit

Code 0 is deliberately set by developers to indicate successful completion. Technically, it means the foreground process exited without attaching to a specific container.

What to Do When a Container Exits with Code 0

Check the container logs to identify which library caused the exit.

Review the library’s code to confirm why it triggered a normal exit and verify that the container behaved as expected.

Exit Code 1: Application Error

Code 1 indicates the container stopped because of either an application programming error (e.g., division by zero) or an invalid reference in the image specification.

What to Do When a Container Exits with Code 1

Inspect container logs for missing files listed in the image spec and correct the image path if needed.

If no bad reference is found, examine the logs for application errors and debug the offending library.

Exit Code 125: Container Failed to Run

Code 125 means the docker run command was invoked but did not execute successfully. Common reasons include undefined flags, insufficient permissions for the user defined in the image, or incompatibility between the container engine and the host OS/hardware.

What to Do When a Container Exits with Code 125

Verify the command syntax is correct.

Ensure the user or context has sufficient privileges to create the container on the host.

If the engine offers alternative options, try docker start instead of docker run.

Test running other containers with the same user; if they fail, reinstall the engine or resolve compatibility issues.

Exit Code 126: Command Invocation Error

Code 126 indicates the specified command in the image could not be called, often due to missing dependencies in CI scripts.

What to Do When a Container Exits with Code 126

Check the logs to see which command failed to invoke.

Run the container without a command to isolate the issue.

Troubleshoot the command syntax and ensure all dependencies are available.

Correct the container specification and retry.

Exit Code 127: File or Directory Not Found

Code 127 means the command referenced a file or directory that does not exist inside the image.

What to Do When a Container Exits with Code 127

Identify the failing command and verify that the file path or name exists in the image.

Exit Code 128: Invalid Exit Parameter

Code 128 occurs when the container’s code triggers an exit with a non‑integer or out‑of‑range value (valid range is 0‑255).

What to Do When a Container Exits with Code 128

Check logs to determine which library issued the invalid exit.

Fix the code to provide a valid integer exit status.

Exit Code 134: Abnormal Termination (SIGABRT)

Code 134 indicates the container aborted itself, typically via the libc abort() function or a failed assert() macro.

What to Do When a Container Exits with Code 134

Inspect logs to find which library triggered the SIGABRT signal.

Confirm whether the abort was expected (e.g., debug mode); if not, debug the library to prevent the abort.

Exit Code 137: Immediate Termination (SIGKILL)

Code 137 means the container received a SIGKILL signal from the host OS, causing an abrupt stop. Causes include manual docker kill, kill -9, Kubernetes termination after the grace period, or OOM‑killer actions.

What to Do When a Container Exits with Code 137

Check host logs for events preceding the SIGKILL and see if a SIGTERM was sent first.

If a SIGTERM was sent, verify the container handles it gracefully.

If no SIGTERM and OOMKilled appears, investigate memory pressure on the host.

Exit Code 139: Segmentation Fault (SIGSEGV)

Code 139 indicates the container received a SIGSEGV signal, a memory‑access violation caused by coding errors, binary/library incompatibility, or hardware/configuration issues.

What to Do When a Container Exits with Code 139

Ensure the process handles SIGSEGV and can report a stack trace.

If deeper debugging is needed, configure the OS to allow the program to continue after a segfault for investigation.

If the issue cannot be reproduced, examine the host’s memory subsystem for faults.

Exit Code 143: Graceful Termination (SIGTERM)

Code 143 means the container received a SIGTERM signal, requesting a normal shutdown. This usually occurs when Docker or Kubernetes stops the container, and the container exits cleanly.

What to Do When a Container Exits with Code 143

Generally no action is required; the container terminated as expected. If needed, check host or kubelet logs to see when the SIGTERM was sent.

Exit Code 255: Exit Status Out of Range

Code 255 indicates the container’s entrypoint exited with an unknown status outside the 0‑255 range, meaning the reason for termination is unclear.

What to Do When a Container Exits with Code 255

If the container runs in a VM, delete and recreate the overlay network.

If that fails, recreate the VM and rerun the container.

Otherwise, exec into the container and inspect the entrypoint process logs for clues.