How to fix Error response from daemon: OCI runtime create failed: runsc error in Docker

DockerADVANCEDHIGH

This error occurs when Docker cannot start a container using gVisor's runsc runtime. Common causes include incorrect installation, misconfigured Docker daemon, kernel incompatibilities, or SELinux restrictions.

What this error means

The "OCI runtime create failed: runsc error" message indicates that Docker attempted to start a container using gVisor's runsc runtime but encountered a failure during container creation. gVisor is a user-space kernel that provides an additional layer of isolation between containers and the host system by intercepting and handling system calls. When you configure Docker to use runsc as the runtime (instead of the default runc), Docker delegates container creation to gVisor. If runsc fails to initialize the sandbox, create the container filesystem, or set up the necessary isolation primitives, this error is thrown. The error is often accompanied by more specific details in Docker's error output or in runsc's debug logs, such as "operation not permitted," "invalid argument," or "cannot create sandbox." These details are crucial for diagnosing the root cause.

How to fix "Error response from daemon: OCI runtime create failed: runsc error"

1Verify runsc installation

First, confirm that runsc is properly installed and accessible:

bash

which runsc
runsc --version

If runsc is not found, install it following the official gVisor installation guide:

bash

# Add the gVisor repository key
curl -fsSL https://gvisor.dev/archive.key | sudo gpg --dearmor -o /usr/share/keyrings/gvisor-archive-keyring.gpg

# Add the repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/gvisor-archive-keyring.gpg] https://storage.googleapis.com/gvisor/releases release main" | sudo tee /etc/apt/sources.list.d/gvisor.list > /dev/null

# Install runsc
sudo apt-get update && sudo apt-get install -y runsc

Ensure runsc is in a location readable and executable by all users (important for unprivileged operation):

bash

ls -la $(which runsc)
# Should show: -rwxr-xr-x ... /usr/bin/runsc

2Configure Docker to use runsc runtime

Add gVisor as a runtime option in Docker's daemon configuration. Edit /etc/docker/daemon.json:

json

{
  "runtimes": {
    "runsc": {
      "path": "/usr/bin/runsc"
    }
  }
}

For more control, you can add runtime arguments:

json

{
  "runtimes": {
    "runsc": {
      "path": "/usr/bin/runsc",
      "runtimeArgs": [
        "--platform=systrap",
        "--network=sandbox"
      ]
    },
    "runsc-debug": {
      "path": "/usr/bin/runsc",
      "runtimeArgs": [
        "--debug-log=/tmp/runsc/",
        "--debug",
        "--strace"
      ]
    }
  }
}

Restart Docker to apply changes:

bash

sudo systemctl restart docker

Verify the runtime is registered:

bash

docker info | grep -A5 "Runtimes"

3Check kernel compatibility

gVisor requires specific kernel features and has known issues with certain kernel versions. Check your kernel version:

bash

uname -r

Known problematic kernel versions:
- Linux 5.1 to 5.3.15
- Linux 5.4.2
- Linux 5.5

If you're running one of these versions, upgrade your kernel:

bash

# Ubuntu/Debian
sudo apt-get update
sudo apt-get upgrade linux-generic

# Check for available kernels
apt list --installed | grep linux-image

Minimum kernel requirements:
- Kernel 4.14.77+ recommended
- Kernel must support user namespaces

Verify user namespace support:

bash

cat /proc/sys/kernel/unprivileged_userns_clone
# Should return 1

If disabled, enable it:

bash

sudo sysctl -w kernel.unprivileged_userns_clone=1
echo "kernel.unprivileged_userns_clone=1" | sudo tee /etc/sysctl.d/99-userns.conf

4Handle SELinux restrictions

If SELinux is enabled, it may block gVisor operations. Check SELinux status:

bash

getenforce

gVisor doesn't support setting SELinux labels. For containers using runsc, disable SELinux for specific containers:

bash

docker run --runtime=runsc --security-opt label=disable <image>

Or run in permissive mode temporarily for testing:

bash

sudo setenforce 0

Note: Disabling SELinux reduces security. In production, consider using gVisor's built-in isolation instead of relying on SELinux for container isolation.

For Docker Compose:

yaml

services:
  myapp:
    runtime: runsc
    security_opt:
      - label:disable

5Enable debug logging to diagnose the issue

If the error persists, enable gVisor debug logging to get detailed information:

Configure a debug runtime in /etc/docker/daemon.json:

json

{
  "runtimes": {
    "runsc-debug": {
      "path": "/usr/bin/runsc",
      "runtimeArgs": [
        "--debug-log=/tmp/runsc/",
        "--debug",
        "--strace"
      ]
    }
  }
}

Important: The trailing / in --debug-log=/tmp/runsc/ is required to interpret it as a directory.

Create the log directory and set permissions:

bash

sudo mkdir -p /tmp/runsc
sudo chmod 777 /tmp/runsc

Restart Docker and run with the debug runtime:

bash

sudo systemctl restart docker
docker run --runtime=runsc-debug hello-world

Check the logs:

bash

ls -la /tmp/runsc/
# Look for files ending in .create for container creation issues
# Files ending in .boot contain application syscall traces
cat /tmp/runsc/runsc.log.*.create

6Fix 'operation not permitted' errors

The "operation not permitted" error often indicates permission or namespace issues.

Check if Docker is running in rootless mode:

bash

docker info | grep "rootless"

gVisor has limited support for rootless Docker. If running rootless, try with root Docker instead.

Verify /proc/self/exe accessibility:

The error "fork/exec /proc/self/exe: operation not permitted" suggests issues with executing runsc. Ensure:

bash

# runsc can re-execute itself
ls -la /proc/self/exe

Check cgroup configuration:

bash

# Verify cgroup v2 (unified hierarchy)
mount | grep cgroup
cat /sys/fs/cgroup/cgroup.controllers

For cgroup v2 systems, ensure Docker is configured properly:

json

{
  "exec-opts": ["native.cgroupdriver=systemd"],
  "runtimes": {
    "runsc": {
      "path": "/usr/bin/runsc"
    }
  }
}

7Test with a minimal container

Before debugging complex containers, verify runsc works with a minimal test:

bash

# Test basic functionality
docker run --runtime=runsc --rm hello-world

# Test with a simple shell
docker run --runtime=runsc --rm -it alpine:latest echo "gVisor working!"

If these work but your application fails, the issue is likely application-specific:

Common application compatibility issues:
- Direct hardware access (not supported)
- Certain system calls not implemented in gVisor
- /dev/mem or other device files
- Specific kernel features your app requires

Check gVisor's compatibility documentation for your use case:

bash

# Run with strace to see which syscalls are failing
docker run --runtime=runsc-debug --rm your-image
cat /tmp/runsc/runsc.log.*.boot | grep -i "not implemented"

Advanced notes

Understanding gVisor Architecture: gVisor (runsc) implements a user-space kernel called Sentry that intercepts system calls from the containerized application. This provides stronger isolation than traditional containers but with some compatibility and performance trade-offs. Not all system calls are implemented, which can cause some applications to fail.

Platform Selection: gVisor supports multiple platforms for system call interception:
- systrap: Uses SIGSYS signal (default, recommended)
- kvm: Uses KVM for hardware virtualization (better performance, requires KVM)

Configure in daemon.json:

json

{
  "runtimes": {
    "runsc-kvm": {
      "path": "/usr/bin/runsc",
      "runtimeArgs": ["--platform=kvm"]
    }
  }
}

Network Modes: gVisor's default sandbox network isolates containers from the host network stack. The embedded DNS server binds to 127.0.0.10 on the loopback interface. For Docker user-defined bridge networks, you may see DNS resolution issues because the sandbox cannot access the host's DNS server without breaking isolation.

Containerd Integration: For Kubernetes or containerd-based setups, configure containerd's config.toml:

toml

[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runsc]
  runtime_type = "io.containerd.runsc.v1"

GPU Support: gVisor has experimental GPU support through nvproxy. For GPU workloads:

bash

docker run --runtime=runsc --gpus all nvidia/cuda:latest nvidia-smi

Note: Rootless mode with GPU is not supported and will fail with "operation not permitted."

Debugging Sandbox Failures: For "cannot create sandbox" errors, check:
1. User namespace support in kernel
2. Mount namespace permissions
3. Seccomp and AppArmor profiles
4. Available file descriptors (ulimit -n)

bash

# Check system limits
ulimit -a
cat /proc/sys/fs/file-max

Performance Tuning: gVisor adds overhead due to syscall interception. For performance-critical workloads:
- Use --platform=kvm if available
- Reduce syscall-heavy operations
- Consider using runc for performance-critical containers and runsc for untrusted workloads

How to fix Error response from daemon: OCI runtime create failed: runsc error in Docker

What this error means

Typical symptoms

Common causes

How to fix "Error response from daemon: OCI runtime create failed: runsc error"

Advanced notes

Related errors

Official resources & further reading