OCI runtime create failed
The low-level container runtime (runc) failed to construct or start the container process due to invalid entrypoints, mount failures, or system level conflicts.
Usually happens because:
- ☑ Entrypoint script has Windows CRLF line endings
- ☑ Missing execution permission on script file
- ☑ CPU architecture mismatch on host machine
🔍 Quick Checklist:
What is OCI runtime create failed?
This error is thrown by Docker when runc (the open-source OCI container spawning runtime) fails to create, map, or start the container process on the system level. Since Docker depends on runc to establish system namespaces, cgroups, and mounting points, any lower-level failure (such as missing execution files in the entrypoint path, mounting non-existent directories, or permission issues on execution targets) triggers this error.
Common Causes
- Non-existent executable or entrypoint: The script/binary defined inside ENTRYPOINT or CMD does not exist in the image filesystem.
- Invalid volume mount paths: Trying to bind directories that do not exist or violate OS sandboxing rules.
- Mismatched CPU architecture: Trying to run arm64 binaries on non-transpiled x86_64 host machines.
| Cause | Frequency |
|---|---|
| Missing executable or entrypoint script | ⭐⭐⭐⭐⭐ |
| Invalid volume mount directories | ⭐⭐⭐⭐ |
| Incompatible architecture binaries | ⭐⭐⭐ |
Common Mistakes
- Writing ENTRYPOINT scripts on Windows and committing them to git with CRLF line endings, causing runc to fail with 'file not found' inside Linux containers.
- Leaving out the execution permissions flag (`chmod +x entrypoint.sh`) before building images.
How to Fix
Docker Operations & Verification
Override the default entrypoint to run an interactive shell and inspect internal paths.
$ docker run --entrypoint /bin/sh -it my-broken-image
/ # ls -l /app
# Check if your starting scripts are placed in the correct directoriesPlatform Specific Fixes
Troubleshoot runc system calls and logs on Linux servers.
# Inspect host system dmesg for runc errors
dmesg | grep -i runc
# Verify runc package installations
runc --versionBest Practices
- Set up `.gitattributes` to enforce `* text eol=lf` on bash scripts.
- Always check file permissions inside the Dockerfile using `RUN chmod +x /path/to/script.sh`.
Frequently Asked Questions (FAQ)
Q: What does OCI runtime create failed mean?
It means runc (the container runtime engine) failed to set up namespaces, cgroups, or mount points, or could not execute the entrypoint script.
Q: How do I fix 'no such file or directory' errors inside OCI create failed?
This usually happens when the script defined in ENTRYPOINT has DOS line endings (\r\n) instead of Unix line endings (\n), making Linux fail to load it. Run 'dos2unix' on the script before building.
Q: Why does it happen on directory mounts?
If the path mapped inside the container conflicts with read-only system files or root nodes, runc aborts mapping.
Q: How do I bypass entrypoints?
Override it via command line: 'docker run --entrypoint /bin/bash -it <image>'.