Exit Code 127
The command specified inside the container could not be found, or its interpreter (shell) is missing in the base image.
Usually happens because:
- ☑ Typo in command name or path
- ☑ Missing shell interpreter (/bin/bash) in Alpine
- ☑ Hidden Windows CRLF characters in shebang line
🔍 Quick Checklist:
What is Exit Code 127?
Exit code 127 is a standard POSIX error indicating 'Command not found'. In Docker, this occurs when you try to execute a command, script, or binary inside a container, but the shell or OS cannot find it. This is commonly caused by: 1) typing the command name or path incorrectly, 2) referencing an interpreter (like #!/bin/bash) that is not installed in lightweight base images like Alpine, or 3) missing library dependencies (like dynamic linkers) required by compiled binaries.
Common Causes
- Command or binary name typo: Typo in the name of the executable (e.g. running 'pyhton' instead of 'python').
- Missing interpreter shell: Calling '/bin/bash' inside Alpine base images which only bundle '/bin/sh' by default.
- Missing dynamic linker dependencies: Trying to run a compiled binary that depends on shared libraries (e.g. glibc) missing from the image.
| Cause | Frequency |
|---|---|
| Command name or path spelling typo | ⭐⭐⭐⭐⭐ |
| Missing shell interpreter (/bin/bash) | ⭐⭐⭐⭐ |
| Missing binary shared library links | ⭐⭐⭐ |
Common Mistakes
- Assuming bash is installed in all Linux base images. Lightweight images (like alpine or busybox) use ash/sh to reduce footprint size.
- Neglecting missing dynamic linkers when copying compiled Go or C++ binaries into scratch or alpine images.
How to Fix
Docker Operations & Verification
If your application startup script depends on bash, you must explicitly install it in Alpine-based Dockerfiles.
FROM alpine:3.18
# Fix: install bash to resolve missing /bin/bash errors
RUN apk add --no-cache bash
COPY run.sh .
ENTRYPOINT ["/bin/bash", "run.sh"]Platform Specific Fixes
Verify file presence inside the container using interactive shell bypass.
docker run -it --entrypoint /bin/sh my-broken-image
# Inside the container, check PATH variables
echo $PATHBest Practices
- Always test scripts locally inside container environments using interactive shell mounting before deploying.
- Include library compatibility tools (`libc6-compat`) when running precompiled packages inside Alpine.
Frequently Asked Questions (FAQ)
Q: What is exit code 127?
Exit code 127 indicates that a command or binary specified inside the container was not found, meaning it cannot be located in the image's PATH.
Q: Why does /bin/bash fail in Alpine?
Alpine Linux is designed to be extremely small and does not include bash by default. It uses BusyBox ash (accessed via /bin/sh). To fix this, change your script's shebang to '#!/bin/sh' or install bash using 'RUN apk add --no-cache bash' in your Dockerfile.
Q: What is the meaning of 'not found' on an existing file?
If you see 'run.sh: not found' but the file clearly exists, it is usually because the script has Windows-style CRLF line endings. The system looks for the interpreter '/bin/sh\r' which does not exist, triggering exit code 127. Run 'dos2unix' on the file.
Q: How do I install glibc compatibility in Alpine?
Add 'RUN apk add --no-cache libc6-compat' to your Dockerfile to supply the missing shared library references.