Exit code 126: The command was found but could not be executed

Exit code 126 means the file exists but the system refused to run it — usually a missing executable bit, a non-executable file being invoked as a command, or a mount that forbids execution.

Applies to: All Kubernetes versions, Linux nodes

What it means

The shell convention reserves 126 for a command that was located but could not be invoked. The file is there; the kernel or the shell declined. In containers this is almost always a permissions or file-format problem introduced at build time. Copying a script into an image without setting the executable bit produces it. So does copying from a filesystem that does not carry Unix permissions, such as a Windows checkout, where the executable bit is lost in transit. It is worth separating from 127, which means the file was not found at all — 126 tells you the path in your spec is correct, which narrows the problem considerably.

Most common causes

• The entrypoint script does not have the executable bit set in the image.
• The file was added from a Windows or archive source that did not preserve permissions.
• A directory was named where a file was expected.
• The binary is on a volume mounted with noexec.
• A shebang line pointing at an interpreter that exists but is not itself executable.
• runAsUser is set to a user with no execute permission on the file.

How to diagnose it

1. Read the message in the logs or events — it usually says permission denied alongside the path.
2. Inspect the file's mode inside the image: run the image locally with an overridden entrypoint and check with ls -l.
3. Check the effective user: compare runAsUser in the pod spec against the file's owner and mode.
4. If the binary lives on a mounted volume, check the mount options for noexec.
5. Verify the file is a file and not a directory — a volume mounted over the expected path can replace it with a directory.

How to fix it

1. Set the executable bit at build time: RUN chmod +x /path/to/entrypoint.sh, or use COPY --chmod=0755.
2. Normalise line endings on scripts. A CRLF shebang makes the interpreter path unparseable and can surface as a permission error.
3. Run as a user that has execute permission, or adjust the file's ownership during the build.
4. Do not place executables on volumes mounted noexec; bake them into the image instead.
5. Check that a volume mount is not shadowing the file with a directory of the same path.

Notes

Because the executable bit is stored in the image layer, this failure is fully reproducible outside the cluster. Running the image locally is faster than any amount of investigation inside Kubernetes.

Related

• Exit code 127 — Command not found
• RunContainerError — The container was created but failed to start

Sources

• GNU Bash Reference Manual — Exit Status
• Kubernetes documentation — Configure a Security Context for a Pod or Container
• Kubernetes documentation — Debug Pods