Exit code 255: An out-of-range or application-specific exit status

255 is the highest value an exit status can hold. It usually means a program returned -1 or a value above 255 that was truncated, or it is an application's own convention for a fatal error.

Applies to: All Kubernetes versions, Linux nodes

What it means

Exit statuses are eight bits, so only 0–255 can be represented. A program returning -1 produces 255, and a program returning any value congruent to 255 modulo 256 produces the same. Because of this, 255 accumulates several unrelated meanings: an explicit fatal-error convention (SSH and some database tools use it), a negative return value from a program written as if the range were signed, and a truncated larger value. It carries no standard meaning of its own, so the logs matter more here than for almost any other code.

Most common causes

• A program returning -1 from main or calling exit(-1).
• A tool that uses 255 as its own fatal-error convention, such as SSH.
• An exit status computed arithmetically and passed out of range.
• A wrapper script propagating a status incorrectly.
• An application-specific error code that happens to be 255.

How to diagnose it

1. Read the previous logs first: kubectl logs POD --previous. The code will not tell you anything the logs do not.
2. Check the application's documented exit codes, if it has any.
3. Inspect any wrapper script for how it computes and propagates the status.
4. Confirm the termination reason in kubectl describe pod POD to rule out a signal.

How to fix it

1. Fix whatever the logs report — the code itself is not actionable.
2. Use exit statuses in the 0–255 range explicitly, and prefer small documented values over negative ones.
3. Make wrapper scripts exec the real process so the status is passed through unmodified.

Notes

Because 255 also results from truncation, treating it as a specific error class in alerting will group genuinely unrelated failures. It is better read as "the application failed and did not use a meaningful code".

Related

• Exit code 1 — General application error
• Exit code 128 — Invalid exit argument, and the base of the signal range

Sources

• GNU Bash Reference Manual — Exit Status
• Linux manual page — exit(3)
• Kubernetes documentation — Pod Lifecycle: container states