This error occurs when Docker fails to initialize the btrfs storage driver. It typically happens when the underlying filesystem is not btrfs, btrfs-progs is not installed, or Docker data is corrupted. The fix usually involves verifying your filesystem type, installing required packages, or switching to a different storage driver like overlay2.
The Docker daemon uses storage drivers (also called graphdrivers) to manage layered filesystems for container images and layers. The btrfs storage driver leverages btrfs's built-in copy-on-write capabilities for efficient storage. When you see "error initializing btrfs driver," Docker is unable to start because it cannot use the btrfs storage driver. This can happen for several reasons: 1. **Wrong filesystem**: Docker is configured to use btrfs, but /var/lib/docker is on a different filesystem (ext4, xfs, etc.) 2. **Missing dependencies**: The btrfs-progs package is not installed 3. **Corrupted state**: The Docker data directory has corrupted btrfs subvolumes 4. **Permission issues**: In rootless Docker setups, btrfs operations may fail due to missing privileges 5. **Kernel incompatibility**: The kernel lacks btrfs support or has incompatible module versions Note that btrfs as a Docker storage driver is deprecated on CentOS/RHEL and has known issues. Docker recommends using overlay2 as the default storage driver unless you have specific requirements for btrfs.
First, verify what filesystem /var/lib/docker is actually using:
# Check the filesystem type for /var/lib/docker
df -hT /var/lib/docker
# Or check the partition where Docker data lives
lsblk -fIf the output shows ext4, xfs, or anything other than btrfs, Docker cannot use the btrfs driver on this partition. You have two options:
1. Switch to a compatible storage driver (overlay2 is recommended)
2. Move /var/lib/docker to an actual btrfs partition
If you're actually running on a btrfs filesystem, ensure the required tools are installed:
# Debian/Ubuntu
sudo apt-get update
sudo apt-get install btrfs-progs
# RHEL/CentOS (note: btrfs is deprecated on RHEL 8+)
sudo yum install btrfs-progs
# Fedora
sudo dnf install btrfs-progs
# SUSE/openSUSE
sudo zypper install btrfsprogs
# Arch Linux
sudo pacman -S btrfs-progsAfter installation, try starting Docker again:
sudo systemctl restart dockerIf you don't specifically need btrfs, switch to overlay2 which is the recommended driver:
# Stop Docker
sudo systemctl stop docker
# Create or edit daemon.json
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<EOF
{
"storage-driver": "overlay2"
}
EOF
# Remove old btrfs data (WARNING: this deletes all containers and images!)
sudo rm -rf /var/lib/docker/btrfs
# Start Docker
sudo systemctl start docker
# Verify the storage driver
docker info | grep "Storage Driver"Important: overlay2 works on ext4, xfs (with d_type=true), and other common filesystems. It does NOT work on btrfs or zfs - you must use the matching driver for those filesystems.
If you're on a real btrfs filesystem but have corrupted data:
# Stop Docker first
sudo systemctl stop docker
# List existing btrfs subvolumes
sudo btrfs subvolume list /var/lib/docker
# If subvolumes are corrupted, remove them
# WARNING: This deletes all containers and images!
sudo btrfs subvolume delete /var/lib/docker/btrfs/subvolumes/*
# Or do a complete cleanup
sudo rm -rf /var/lib/docker/*
# Restart Docker
sudo systemctl start dockerDocker will recreate the necessary directory structure on startup.
For rootless Docker installations on btrfs, the btrfs driver often fails with "operation not permitted". Use fuse-overlayfs instead:
# Create the rootless Docker config directory
mkdir -p ~/.config/docker
# Configure fuse-overlayfs as the storage driver
cat > ~/.config/docker/daemon.json <<EOF
{
"storage-driver": "fuse-overlayfs"
}
EOF
# Install fuse-overlayfs if not present
# Debian/Ubuntu
sudo apt-get install fuse-overlayfs
# Fedora
sudo dnf install fuse-overlayfs
# Restart rootless Docker
systemctl --user restart dockerIf Docker complains about multiple valid graphdrivers, clean up old storage driver data:
# Stop Docker
sudo systemctl stop docker
# Check what's in the Docker directory
ls -la /var/lib/docker/
# Remove directories for drivers you're not using
# Only keep the directory for your chosen driver
sudo rm -rf /var/lib/docker/aufs
sudo rm -rf /var/lib/docker/overlay
sudo rm -rf /var/lib/docker/overlay2
sudo rm -rf /var/lib/docker/devicemapper
# Keep btrfs if that's your chosen driver, or remove it if switching
# Start Docker
sudo systemctl start dockerNote: Removing these directories will delete all associated images and containers.
If you're on a btrfs filesystem and want to use the btrfs driver, configure it explicitly:
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<EOF
{
"storage-driver": "btrfs"
}
EOF
sudo systemctl restart dockerVerify it's working:
docker info | grep "Storage Driver"
# Should show: Storage Driver: btrfs
# Test with a container
docker run --rm hello-worldAfter applying fixes, confirm everything is functioning:
# Check Docker daemon status
sudo systemctl status docker
# Verify the storage driver
docker info | grep -A5 "Storage Driver"
# Run a test container
docker run --rm hello-world
# Check for any warnings in Docker info
docker info 2>&1 | grep -i warningIf Docker starts successfully and the test container runs, the issue is resolved.
Btrfs Storage Driver Deprecation:
The btrfs storage driver is deprecated on RHEL/CentOS 7.4+ and completely removed in RHEL/CentOS 8+. Docker officially recommends overlay2 as the default storage driver for all supported Linux distributions. Only use btrfs if you have specific workload requirements that benefit from btrfs's copy-on-write characteristics.
Kernel Requirements:
Starting from Docker 18.06, the btrfs storage driver requires Linux kernel headers >= 4.12 instead of headers from btrfs-progs. Ensure your system has compatible kernel headers installed:
# Debian/Ubuntu
sudo apt-get install linux-headers-$(uname -r)
# RHEL/CentOS
sudo yum install kernel-headersSUSE Linux Enterprise Server:
SLES is one of the few distributions where btrfs is fully supported as a Docker storage driver. If you're on SLES and see this error, ensure btrfs-progs is installed and /var/lib/docker is on a btrfs partition.
Performance Considerations:
While btrfs and zfs perform better for write-heavy workloads than overlay2, Docker volumes still outperform both. For databases or high I/O applications, use named volumes or bind mounts instead of relying on storage driver performance.
Known Issues (Moby #27653):
The btrfs driver has documented issues with subvolume quotas and snapshot cleanup. If you experience hangs or performance degradation, check the GitHub issue for workarounds.
Kubernetes/kubeadm Compatibility:
kubeadm init may fail with "unsupported graph driver: btrfs" as btrfs is not officially supported. Use:
kubeadm init --ignore-preflight-errors=SystemVerificationOr switch to a supported storage driver before initializing the cluster.
Container Runtime Interface (CRI):
If you're using containerd directly with Kubernetes, configure the snapshotter in containerd's config.toml rather than Docker's daemon.json.
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