RunContainerError: The container was created but failed to start

RunContainerError means creation succeeded but the runtime could not actually start the container process — usually a bad entrypoint, a missing shared library, or a permissions problem.

Applies to: All Kubernetes versions, any container runtime

What it means

This is the stage after CreateContainerError: the container object exists and the runtime tried to run its process. Failures here are typically about the process itself rather than the pod configuration — the binary is missing an interpreter or shared library, the entrypoint is not executable, the working directory does not exist, or the configured user lacks permission to run it. The distinguishing feature is that the image is present and the config resolved, so the problem lives inside the image or in the security context applied to it.

Most common causes

• The entrypoint binary is dynamically linked against libraries the image does not contain — common when copying a binary built on a glibc system into an Alpine image.
• The entrypoint script lacks the executable bit, or has Windows line endings that make the shebang unparseable.
• runAsUser specifies a user that does not exist in the image, or that cannot read the entrypoint.
• The configured workingDir does not exist in the image.
• A read-only root filesystem is set but the process needs to write during startup.
• The image was built for a different architecture than the node.

How to diagnose it

1. Read the message in kubectl describe pod POD; it usually names the failing path or the missing library.
2. Run the image locally with an overridden entrypoint and inspect it: check the binary exists, is executable, and its dynamic dependencies resolve with ldd.
3. Check the effective user: compare runAsUser against the users present in the image.
4. If a read-only root filesystem is set, identify what the process writes at startup and whether it can be redirected to an emptyDir.

How to fix it

1. Build the binary against the same libc as the runtime image, or use a base image that provides the required libraries.
2. Set the executable bit in the Dockerfile and normalise line endings on shell scripts.
3. Use a user that exists in the image, or add it during the build.
4. Create the working directory in the image, or remove workingDir from the spec.
5. Mount an emptyDir at the paths the process needs to write when using a read-only root filesystem.

Notes

A missing shared library often produces a message that names the library rather than the binary, which can be confusing if the binary itself is present and executable. The presence of the entrypoint does not mean it can run.

Related

• CreateContainerError — The runtime failed to create the container
• CrashLoopBackOff — Repeated restarts with increasing delay

Sources

• Kubernetes documentation — Debug Pods
• Kubernetes documentation — Configure a Security Context for a Pod or Container
• Kubernetes documentation — Images