🚨 Docker Error Guide: 'failed to create shim task' Containerd Runtime Startup Failures

Exact Error Message

failed to create shim task is raised by the containerd runtime layer when it cannot launch the process that supervises your container:

docker run --rm alpine true

docker: Error response from daemon: failed to create shim task: OCI
runtime create failed: runc create failed: unable to start container
process: error during container init: error mounting "proc" to rootfs
at "/proc": ... operation not permitted: unknown.

Error response from daemon: failed to create shim task: OCI runtime
create failed: runc create failed: unable to start container process:
exec: "runc": executable file not found in $PATH: unknown

failed to create shim task: failed to create shim: OCI runtime create
failed: ... cgroup ... no such file or directory

The container never reaches “running.” Everything after failed to create shim task: is the real, nested cause.

What the Error Means

Modern Docker doesn’t run containers directly. The daemon talks to containerd, which spawns a shim (containerd-shim-runc-v2) per container; the shim invokes the OCI runtime (runc) to set up namespaces, cgroups, and mounts, then execs your process. “Failed to create shim task” means this chain broke before the container’s process started — typically inside runc create or while the shim itself was launching.

This is a wrapper error, and the message nests its cause: runc create failed, then a specific reason like a mount that’s operation not permitted, a missing runc binary, a cgroup path that doesn’t exist (cgroup v1/v2 mismatch), or a kernel feature the runtime needs but can’t use. Read the innermost clause — that’s where the fix lives. The image is irrelevant here; the problem is the host’s runtime, cgroups, or kernel.

Common Causes

• Broken or missing runc binary — wrong version, not on PATH, or corrupted after an upgrade.
• cgroup v1/v2 mismatch. The daemon/runtime expects one cgroup hierarchy but the host provides the other, so cgroup paths don’t exist.
• Mount/permission restrictions. SELinux, AppArmor, a read-only /proc, or nosuid/restrictive mounts block runc from mounting proc/sysfs.
• Missing kernel features — required namespaces, seccomp, or cgroup controllers disabled in the kernel.
• Disk/inode exhaustion where the shim writes its state, so it can’t create the task files.
• containerd/runc version skew after a partial package upgrade that left mismatched components.
• Resource limits hit — too many running containers exhausting PIDs/cgroups on the host.

How to Reproduce the Error

Make runc unavailable to the daemon’s PATH and start a container (do this on a throwaway host — it breaks all container starts):

which runc            # note the path, e.g. /usr/bin/runc
mv /usr/bin/runc /usr/bin/runc.bak
docker run --rm alpine true

docker: Error response from daemon: failed to create shim task: OCI
runtime create failed: runc create failed: ... exec: "runc": executable
file not found in $PATH: unknown.

Restore with mv /usr/bin/runc.bak /usr/bin/runc.

Diagnostic Commands

Confirm the runtime binaries exist and report sane versions:

docker info | grep -iA2 'Runtimes\|Default Runtime\|cgroup'
runc --version
containerd --version

Check the cgroup version the host is actually using:

stat -fc %T /sys/fs/cgroup

cgroup2fs means cgroup v2; tmpfs means v1. A mismatch with the daemon’s expectation is a frequent cause.

Inspect containerd and the daemon log for the nested runtime error:

journalctl -u containerd --since "10 min ago" | grep -i 'shim\|runc\|cgroup\|oci'
journalctl -u docker --since "10 min ago" | grep -i 'shim task\|runc\|create failed'

Check disk/inodes where state is written and the security modules in play:

df -h /run /var/lib/containerd
df -i /run /var/lib/containerd

Step-by-Step Resolution

Cause: missing/broken runc. Reinstall or restore the runtime, then verify and retry:

runc --version
systemctl restart containerd docker
docker run --rm alpine true

If a package upgrade left version skew, reinstall matching containerd.io (which bundles compatible runc/shim) so the components agree.

Cause: cgroup v1/v2 mismatch. Align the daemon and host. On a cgroup v2 host, ensure the daemon uses the systemd cgroup driver (set "exec-opts": ["native.cgroupdriver=systemd"] in /etc/docker/daemon.json) and restart Docker. The cgroup error path in the log tells you which hierarchy was expected.

Cause: mount/permission restrictions. Read the AppArmor/SELinux denials in journalctl/dmesg; fix the policy rather than disabling security wholesale. A read-only or restrictively mounted /proc//sys on the host must be corrected so runc can mount them into the container.

Cause: disk/inode exhaustion. Free space on /run and /var/lib/containerd, then restart the services. See the no space left on device guide for reclaiming storage.

Cause: missing kernel features. Confirm required namespaces, seccomp, and cgroup controllers are enabled in the kernel; on minimal/managed kernels you may need a different kernel build.

A worked example. After an unattended package upgrade, every docker run on a node failed with failed to create shim task: ... cgroup ... no such file or directory. stat -fc %T /sys/fs/cgroup showed cgroup2fs, but docker info revealed the daemon was still configured with the cgroupfs driver from before the OS bumped to cgroup v2. Setting native.cgroupdriver=systemd in daemon.json and restarting Docker aligned the driver with the host’s cgroup v2 hierarchy, and containers started normally. The fix was rolled into the node image so future hosts ship with the correct driver.

Prevention and Best Practices

• Keep containerd.io, runc, and the shim on matching, package-managed versions; avoid mixing manual and packaged installs.
• Standardize the cgroup driver (systemd on cgroup v2 hosts) across the fleet via daemon.json.
• Monitor /run and /var/lib/containerd for disk and inode pressure before they exhaust.
• Test runtime changes (kernel, AppArmor/SELinux policy, cgroup settings) in staging before fleet rollout.
• After any upgrade that touches container packages, run a smoke docker run --rm alpine true to catch version skew early.

Related Errors

• Docker Error Guide: ‘OCI runtime create failed’ — the inner runtime failure this shim error frequently wraps.
• Docker Error Guide: ‘cannot connect to the Docker daemon’ — a different layer of the daemon/containerd stack failing.
• See more Docker troubleshooting guides.

Frequently Asked Questions

Is this an image problem? No. The shim/runtime fails before your image’s process starts, so the same image runs fine on a correctly configured host. Focus on runc/containerd/cgroups.

What’s the difference between this and ‘OCI runtime create failed’? This error wraps it. The shim is the supervisor process; runc create failed (the OCI runtime error) is usually the nested cause it reports.

Why did it start after an OS upgrade? Upgrades commonly switch hosts to cgroup v2 or bump containerd/runc, creating a driver or version mismatch with the existing Docker config. Re-align the cgroup driver and component versions.

Can restarting Docker fix it? It helps with transient state and version reloads after a reinstall, but it won’t fix a genuine cgroup-driver mismatch, missing runc, or disabled kernel feature — those need a config or package change.