CreateContainerError
This error occurs when the container runtime (containerd) fails to construct or initialize the container process itself on the host.
Usually happens because:
- ☑ Container command or arguments refer to an executable file path missing in the image
- ☑ runAsNonRoot: true is active but the image runs as root (UID 0) by default
- ☑ readOnlyRootFilesystem: true blocks writes to root directories without emptyDir mounts
🔍 Quick Checklist:
What is CreateContainerError?
A 'CreateContainerError' is a pod lifecycle status indicating that the Kubelet has prepared the network sandbox, volumes, and secrets, but the container runtime (containerd) failed to construct the container process. In Kubernetes v1.36, typical causes include trying to run a container command (like a shell script entrypoint) that does not exist in the image, permissions problems with the container process user (non-root directives), or invalid security contexts.
Common Causes
- Non-existent command or script: The entrypoint 'command' or 'args' defined in the pod manifest references a file path that does not exist inside the image (e.g. running '/bin/bash' on an Alpine image containing only '/bin/sh').
- Read-only root filesystem permission blocks: The security context defines 'readOnlyRootFilesystem: true' but the container tries to write temporary log files to root directories.
- Invalid UID/GID security configurations: Enforcing 'runAsNonRoot: true' when the container image's default user is set to root (UID 0).
| Cause | Frequency |
|---|---|
| Typo in CMD/ENTRYPOINT executable binary path | ⭐⭐⭐⭐⭐ |
| runAsNonRoot: true active on a default-root container image | ⭐⭐⭐⭐ |
| readOnlyRootFilesystem: true blocks writes to root folders | ⭐⭐⭐ |
Common Mistakes
- Assuming minimal images contain shell utilities like `/bin/bash` or `curl` (running bash on distroless or alpine images triggers immediate CreateContainerError).
- Configuring `runAsNonRoot: true` without specifying a `runAsUser` UID, if the image does not define a USER directive in its Dockerfile.
How to Fix
Kubernetes Operations & Verification
Configure container user identity parameters (UID) to enforce non-root execution rules without triggering container startup failures in Kubernetes v1.36.
apiVersion: v1
kind: Pod
metadata:
name: secure-app-pod
spec:
securityContext:
# 1. Enforce non-root user checks
runAsNonRoot: true
# 2. Force non-root UID (user ID 1000)
runAsUser: 1000
fsGroup: 2000
containers:
- name: app
image: node:18-alpine
command: ["node", "app.js"]Platform Specific Fixes
Log directly into nodes to trace containerd runtime start logs.
# 1. Inspect Pod details events for runtime logs
kubectl describe pod app-server
# 2. Check containerd system daemon logs
journalctl -u containerd -n 50 | grep -i "create"Best Practices
- Run and verify container images locally using docker run under identical UID rules before committing resources.
- Adopt distroless images configurations with explicit entrypoint lists.
Frequently Asked Questions (FAQ)
Q: What is the difference between CreateContainerConfigError and CreateContainerError?
CreateContainerConfigError means Kubelet failed to compile the settings (like missing ConfigMaps or Secrets). CreateContainerError means the settings are fine, but the container runtime (containerd) failed to physically build or start the container process (e.g. wrong command or security settings).
Q: Why does my container fail with 'runAsNonRoot: true'?
If you enforce 'runAsNonRoot: true' in your securityContext, the Kubelet checks if the container's default user is root (UID 0). If it is, the Kubelet refuses to start it and throws CreateContainerError. You can resolve this by adding 'runAsUser: 1000' to force a non-root UID.
Q: How do I fix 'executable file not found in $PATH'?
This means the command defined in your YAML ('command: ["/bin/bash"]') does not exist inside the image. For example, minimal images (like Alpine) do not have bash; they use sh ('command: ["/bin/sh"]').
Q: How do I troubleshoot readOnlyRootFilesystem: true failures?
When the filesystem is read-only, any attempt by the application to write files (even temp logs or pid files) will fail. Mount an 'emptyDir' volume on those write directories to allow safe temp writes.