This error occurs when Docker cannot start a container using the Kata Containers runtime, typically due to missing Kata components, incorrect configuration, or lack of hardware virtualization support.
The "OCI runtime create failed: kata runtime error" indicates that Docker attempted to create a container using Kata Containers as the OCI runtime but failed during the container creation process. Kata Containers is an open-source project that provides lightweight virtual machines to run containers with stronger isolation than traditional container runtimes like runc. Unlike standard container runtimes that share the host kernel, Kata Containers launches each container inside its own micro-VM with a dedicated kernel. This requires hardware virtualization support (Intel VT-x/AMD-V) and properly configured virtualization components. The error typically surfaces when the Kata runtime is specified but the system lacks the necessary prerequisites. Common scenarios include: the Kata runtime binaries are not installed or not found in the expected path, the Docker daemon configuration references Kata incorrectly, the host system doesn't support nested virtualization (when running inside a VM), or required Kata components like the hypervisor (QEMU/Firecracker) or guest kernel are missing.
First, check if Kata Containers is installed and its components are present:
# Check if kata-runtime binary exists
which kata-runtime
# Verify kata-runtime version
kata-runtime --version
# Run Kata's built-in system compatibility check
kata-runtime kata-checkIf kata-runtime is not found, install Kata Containers:
On Ubuntu/Debian:
# Add the Kata Containers repository
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.opensuse.org/repositories/home:/katacontainers:/releases:/x86_64:/master/xUbuntu_22.04/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kata-containers.gpg
echo "deb [signed-by=/etc/apt/keyrings/kata-containers.gpg] https://download.opensuse.org/repositories/home:/katacontainers:/releases:/x86_64:/master/xUbuntu_22.04/ /" | sudo tee /etc/apt/sources.list.d/kata-containers.list
sudo apt update
sudo apt install -y kata-runtime kata-containers-imageUsing kata-manager (recommended):
# Download and run kata-manager
bash -c "$(curl -fsSL https://raw.githubusercontent.com/kata-containers/kata-containers/main/utils/kata-manager.sh)"Kata Containers requires hardware virtualization. Verify it's available and enabled:
# Check for CPU virtualization support
cat /proc/cpuinfo | grep -E "(vmx|svm)"
# Run kata-check for comprehensive verification
sudo kata-runtime kata-checkExpected output should show either vmx (Intel VT-x) or svm (AMD-V).
If no output:
1. Reboot and enter BIOS/UEFI settings
2. Enable "Intel Virtualization Technology" or "AMD-V"
3. The setting location varies by manufacturer (usually under CPU, Advanced, or Security)
If running inside a VM, enable nested virtualization:
For VMware:
- Edit VM settings > Processors > Enable "Virtualize Intel VT-x/EPT"
For VirtualBox:
- Settings > System > Processor > Enable "Nested VT-x/AMD-V"
For KVM/QEMU host:
# Enable nested virtualization on the host
sudo modprobe -r kvm_intel
sudo modprobe kvm_intel nested=1Update the Docker daemon configuration to recognize Kata as an available runtime:
# Edit Docker daemon configuration
sudo nano /etc/docker/daemon.jsonAdd or update the runtimes section:
{
"runtimes": {
"kata": {
"path": "/usr/bin/kata-runtime"
},
"kata-qemu": {
"path": "/usr/bin/containerd-shim-kata-qemu-v2"
},
"kata-fc": {
"path": "/usr/bin/containerd-shim-kata-fc-v2"
}
}
}Restart Docker to apply changes:
sudo systemctl daemon-reload
sudo systemctl restart dockerVerify the runtime is available:
docker info | grep -i runtimeExpected output should include kata in the list of runtimes.
Kata requires several components to function. Check they all exist:
# Check for guest kernel
ls -la /usr/share/kata-containers/
# You should see files like:
# - vmlinuz.container (guest kernel)
# - kata-containers.img or kata-containers-initrd.img (root filesystem)
# - OVMF.fd or similar (UEFI firmware, if using UEFI boot)If files are missing, reinstall Kata with all components:
# Using kata-manager
kata-manager install-packages
# Or manually install missing packages (Ubuntu)
sudo apt install kata-runtime kata-containers-image kata-linux-container kata-proxy kata-shimCheck the hypervisor is available:
# For QEMU
which qemu-system-x86_64
# For Firecracker
which firecrackerIf you're using containerd (directly or via Kubernetes), configure it for Kata:
# Edit containerd config
sudo nano /etc/containerd/config.tomlAdd the Kata runtime configuration:
[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.kata]
runtime_type = "io.containerd.kata.v2"
privileged_without_host_devices = true
pod_annotations = ["io.katacontainers.*"]
[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.kata-qemu]
runtime_type = "io.containerd.kata-qemu.v2"
privileged_without_host_devices = trueRestart containerd:
sudo systemctl restart containerdFor Kubernetes, create a RuntimeClass:
apiVersion: node.k8s.io/v1
kind: RuntimeClass
metadata:
name: kata
handler: kataThen reference it in your pod spec:
spec:
runtimeClassName: kataRun a simple test container with Kata to verify it's working:
With Docker:
docker run --rm --runtime=kata alpine uname -rThe kernel version should be different from your host kernel (indicating it's running in a Kata VM).
With containerd (ctr):
sudo ctr image pull docker.io/library/alpine:latest
sudo ctr run --runtime "io.containerd.kata.v2" --rm -t docker.io/library/alpine:latest test-kata uname -rWith nerdctl:
nerdctl run --runtime kata --rm alpine uname -rIf the test fails, check the logs for more details:
# Docker daemon logs
sudo journalctl -u docker.service -n 100 --no-pager
# Containerd logs
sudo journalctl -u containerd.service -n 100 --no-pagerSecurity modules can interfere with Kata operations. Check and adjust if necessary:
For SELinux (CentOS/RHEL/Fedora):
# Check SELinux status
getenforce
# Check for Kata-related denials
sudo ausearch -m avc -ts recent | grep kata
# Temporarily set permissive (for testing only)
sudo setenforce 0If this resolves the issue, create proper SELinux policies rather than leaving permissive.
For AppArmor (Ubuntu/Debian):
# Check AppArmor status
sudo aa-status
# Check for Kata denials
sudo dmesg | grep -i apparmor | tail -20
# Test with AppArmor disabled for the container
docker run --security-opt apparmor=unconfined --runtime=kata alpine uname -rNote: Running with security modules disabled is not recommended for production.
Ensure your Kata version is compatible with Docker/containerd:
# Check versions
kata-runtime --version
docker --version
containerd --versionKnown compatibility issues:
- Kata 2.x with Docker < 20.10: May require specific shim paths
- Docker Engine 23.0: Has a known issue where exiting an exec session stops Kata containers
- Kata with older containerd: May need containerd 1.5+ for v2 runtime API
Update Kata to latest version:
# Using kata-manager
kata-manager install-packages --force
# Or using package manager
sudo apt update && sudo apt upgrade kata-runtimeIf using an older system, consider using Kata 1.x which has different requirements:
# Check available versions
apt-cache madison kata-runtime### Understanding Kata Containers Architecture
Kata Containers provides VM-level isolation for containers. Each Kata container runs inside a lightweight virtual machine with its own kernel, providing:
- Strong isolation: Containers don't share the host kernel
- Security: Kernel vulnerabilities don't affect the host
- Compatibility: Standard container images work without modification
The architecture includes:
- kata-runtime: OCI-compliant runtime binary
- containerd-shim-kata-v2: Containerd runtime handler (Kata 2.x)
- Hypervisor: QEMU, Firecracker, or Cloud Hypervisor
- Guest kernel and initrd: Lightweight Linux kernel and root filesystem
### Firecracker vs QEMU
Kata supports multiple hypervisors:
QEMU (kata-qemu):
- Full-featured VM emulation
- Better compatibility with various workloads
- Supports more device types
- Higher memory overhead
Firecracker (kata-fc):
- Minimal microVM (built by AWS)
- Faster startup times (~125ms)
- Lower memory footprint
- Limited device support
# Use Firecracker runtime
docker run --runtime=kata-fc alpine uname -r
# Use QEMU runtime
docker run --runtime=kata-qemu alpine uname -r### Debugging Kata Issues
Enable debug logging:
# Edit Kata configuration
sudo nano /etc/kata-containers/configuration.toml
# Set enable_debug = true in [hypervisor.qemu] section
[hypervisor.qemu]
enable_debug = trueCheck Kata logs:
sudo journalctl -t kataView hypervisor process:
ps aux | grep -E "(qemu|firecracker)"### Resource Considerations
Kata containers have higher resource requirements than runc containers:
- Memory: Each VM needs minimum ~128MB (configurable)
- CPU: Hypervisor overhead per container
- Disk: Guest kernel and initrd (~50MB)
Configure resources in /etc/kata-containers/configuration.toml:
[hypervisor.qemu]
default_memory = 2048 # MB
default_vcpus = 1### Cloud Provider Support
When running on cloud VMs, nested virtualization support varies:
- AWS: Bare metal instances (*.metal) or specific instance types
- GCP: Enabled by default on most instances
- Azure: Requires specific VM sizes (Dv3, Ev3 series)
- DigitalOcean: Not supported on standard droplets
Check your cloud provider's documentation for nested virtualization support.
unable to configure the Docker daemon with file /etc/docker/daemon.json
How to fix 'unable to configure the Docker daemon with file daemon.json' in Docker
docker: Error response from daemon: OCI runtime create failed: container_linux.go: starting container process caused: exec: "/docker-entrypoint.sh": stat /docker-entrypoint.sh: no such file or directory
How to fix 'exec: entrypoint.sh: no such file or directory' in Docker
image operating system "linux" cannot be used on this platform
How to fix 'image operating system linux cannot be used on this platform' in Docker
dockerfile parse error line 5: unknown instruction: RRUN
How to fix 'unknown instruction' Dockerfile parse error in Docker
manifest unknown: manifest unknown
How to fix 'manifest unknown' in Docker