This error occurs when Docker's containerd runtime fails to create a filesystem snapshot for a container. Common causes include corrupted storage, missing snapshot directories, disk space issues, or storage driver misconfiguration.
The "error creating containerd snapshot" error indicates that Docker's underlying container runtime (containerd) failed to create the necessary filesystem snapshot when starting or creating a container. Containerd uses snapshotters to manage the layered filesystem that containers rely on, and this error means something went wrong during that process. In Docker's architecture, containerd handles the low-level container operations including image management and filesystem snapshots. When you run a container, containerd creates a snapshot of the image layers and adds a writable layer on top. This snapshot mechanism is what allows containers to have their own isolated filesystem while sharing the underlying image layers efficiently. This error typically points to problems with the storage backend: corrupted snapshot metadata, missing snapshot directories (often after a system crash or improper shutdown), insufficient disk space, or incompatibility between the storage driver and the underlying filesystem. It's more common in environments with heavy container churn, after system reboots, or when using non-standard storage configurations.
First, verify there's sufficient disk space for container operations. Snapshot creation requires free space on the Docker storage partition:
# Check overall disk usage
df -h
# Check Docker's disk usage specifically
docker system df
# See detailed breakdown by component
docker system df -vIf disk space is low (below 10-15% free), clean up unused resources:
# Remove unused containers, images, networks, and build cache
docker system prune -a
# Also remove unused volumes (use with caution)
docker system prune -a --volumesA daemon restart often resolves transient snapshot issues by reinitializing containerd's state:
# On Linux with systemd
sudo systemctl restart docker
# Check Docker and containerd status
sudo systemctl status docker
sudo systemctl status containerd
# On Docker Desktop (Windows/Mac)
# Right-click Docker icon in system tray > RestartAfter restart, check if containerd is running properly:
# Verify containerd is operational
sudo ctr version
# List containerd namespaces
sudo ctr namespaces listCheck that containerd's snapshot directories exist and are accessible:
# Check containerd snapshot directories
ls -la /var/lib/docker/containerd/daemon/io.containerd.snapshotter.v1.overlayfs/
# For standalone containerd installations
ls -la /var/lib/containerd/io.containerd.snapshotter.v1.overlayfs/snapshots/
# Verify permissions (should be owned by root)
stat /var/lib/docker/containerd/If directories are missing, Docker daemon restart should recreate them. If permission issues exist:
# Fix ownership (if needed)
sudo chown -R root:root /var/lib/docker/containerd/Verify the storage driver and snapshotter are compatible with your filesystem:
# Check current storage driver and containerd configuration
docker info | grep -E "Storage Driver|containerd"
# Check filesystem type of Docker's data directory
df -T /var/lib/dockerCommon compatibility requirements:
- overlay2/overlayfs: Requires ext4, xfs, or btrfs (with d_type support)
- btrfs: Requires btrfs filesystem
- zfs: Requires zfs filesystem
If you see warnings about snapshotter compatibility:
# Check journald logs for snapshotter warnings
sudo journalctl -u docker | grep -i "snapshotter"To configure the snapshotter explicitly in /etc/docker/daemon.json:
{
"storage-driver": "overlay2"
}If specific images consistently fail, remove and re-pull them to ensure clean layer data:
# Remove the problematic image
docker rmi <image_name>:<tag>
# Force remove if the image is in use
docker rmi -f <image_name>:<tag>
# Re-pull the image
docker pull <image_name>:<tag>
# Verify the image is complete
docker inspect <image_name>:<tag> | grep -A 10 "RootFS"For locally built images, rebuild without cache:
docker build --no-cache -t <image_name>:<tag> .If the error persists, clearing containerd's metadata can help (this is more invasive):
# Stop Docker
sudo systemctl stop docker
sudo systemctl stop containerd
# Backup and remove containerd metadata (keeps images)
sudo mv /var/lib/docker/containerd /var/lib/docker/containerd.bak
# Restart Docker (will recreate containerd state)
sudo systemctl start docker
# Test container creation
docker run --rm hello-worldIf successful, you can remove the backup:
sudo rm -rf /var/lib/docker/containerd.bakNote: This may require re-pulling some images.
If all else fails, perform a complete storage reset:
Docker Desktop (Windows/Mac):
Settings > Troubleshoot > Reset to factory defaults
Linux - Full reset:
# Stop Docker and containerd
sudo systemctl stop docker
sudo systemctl stop containerd
# BACKUP any important volumes first!
# List volumes to identify important data
docker volume ls
# Remove Docker's data directory
sudo rm -rf /var/lib/docker
sudo rm -rf /var/lib/containerd
# Restart Docker (will recreate directories)
sudo systemctl start docker
# Verify Docker is working
docker run --rm hello-worldWarning: This removes ALL Docker data including containers, images, volumes, and networks. Export important data before proceeding.
Understanding containerd snapshotters: Containerd uses snapshotters to manage filesystem layers. The default overlayfs snapshotter creates layer diffs efficiently using the kernel's OverlayFS. Other snapshotters include btrfs, zfs, and devmapper, each optimized for different storage backends.
Checking containerd health directly:
# List snapshots in containerd
sudo ctr -n moby snapshots ls
# Check for orphaned snapshots
sudo ctr -n moby snapshots list | grep -v "committed"
# View containerd's runtime state
sudo ctr -n moby containers listDocker Engine 29+ and containerd image store: Docker Engine 29.0+ can use containerd's image store directly (enabled via "features": {"containerd-snapshotter": true} in daemon.json). This changes how snapshots are managed and may affect troubleshooting steps.
Kubernetes/K3s/RKE2 environments: In Kubernetes clusters using containerd directly (not Docker), the snapshot paths differ:
# K3s containerd path
/var/lib/rancher/k3s/agent/containerd/
# RKE2 containerd path
/var/lib/rancher/rke2/agent/containerd/Devmapper snapshotter issues: If using the devmapper snapshotter (common in older setups), you may encounter "object already exists" errors. These often require manual cleanup:
# Check devmapper devices
sudo dmsetup ls
# Remove orphaned devmapper devices (use with caution)
sudo dmsetup remove <device_name>Race conditions in CI/CD: Heavy parallel container operations can overwhelm the snapshotter. Implement serialization:
# GitHub Actions example
jobs:
build:
concurrency:
group: docker-${{ github.ref }}
cancel-in-progress: falseContainerd configuration: For advanced tuning, edit /etc/containerd/config.toml:
[plugins."io.containerd.grpc.v1.cri".containerd]
snapshotter = "overlayfs"
[plugins."io.containerd.snapshotter.v1.overlayfs"]
root_path = "/var/lib/containerd/io.containerd.snapshotter.v1.overlayfs"Windows containers: On Windows, containerd uses the Windows container isolation (wcow) snapshotter. Snapshot errors on Windows often relate to Hyper-V isolation issues or Windows Update pending restarts.
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