Exit code 2: Misuse of a shell builtin, or an application-specific usage error

Exit code 2 conventionally means incorrect usage — a shell builtin misused, or a program rejecting its own arguments. In containers it usually means the command line in the pod spec is wrong.

Applies to: All Kubernetes versions, Linux nodes

What it means

Bash uses status 2 for misuse of a shell builtin, and many command-line programs follow the same convention for invalid arguments, distinguishing it from status 1 for a runtime failure. In a container this usually points at the pod spec's command and args rather than at the application's internals. The distinction that matters is that command overrides the image's ENTRYPOINT and args overrides its CMD — setting one without understanding the other is the most common way to hand a program arguments it cannot parse. Not every program follows the convention, so 2 should be read as a strong hint rather than a certainty.

Most common causes

• The pod spec's args do not match what the image's entrypoint expects.
• command was set, replacing the image's entrypoint, and the arguments that made sense for the original entrypoint no longer do.
• A flag was passed that the program's version does not support.
• A YAML string that should have been a list, so the whole command arrives as a single argument.
• A shell builtin used incorrectly inside an entrypoint script.
• An application that simply uses 2 for its own error conditions, ignoring the convention.

How to diagnose it

1. Read the logs — usage errors normally print the usage text: kubectl logs POD --previous.
2. Look at the exact command the container was given: kubectl get pod POD -o jsonpath='{.spec.containers[*].command} {.spec.containers[*].args}'.
3. Compare against the image's own entrypoint and command with docker inspect IMAGE.
4. Watch for the single-string mistake — args: ["--flag value"] passes one argument, while args: ["--flag", "value"] passes two.

How to fix it

1. Correct the arguments so they match the entrypoint that is actually in effect.
2. Prefer setting only args and leaving the image's entrypoint intact, unless you specifically intend to replace it.
3. Split arguments into separate list elements rather than relying on shell-style splitting, which does not happen in the exec form.
4. Pin the image tag so a flag that exists today does not disappear in a newer version.

Notes

The convention is not enforced anywhere. Treat 2 as pointing at the command line first, but do not conclude the application is fine just because it did not use 1.

Related

• Exit code 1 — General application error
• Exit code 127 — Command not found

Sources

• GNU Bash Reference Manual — Exit Status
• Kubernetes documentation — Define a Command and Arguments for a Container
• Kubernetes documentation — Debug Running Pods