This error occurs when Docker tries to use the AUFS storage driver on a filesystem that already uses OverlayFS. AUFS cannot be layered on top of overlay filesystems. The solution is to migrate to the overlay2 storage driver, which is the modern recommended driver for most Linux systems.
The Docker daemon uses a storage driver (also called graphdriver) to manage image layers and container filesystems. AUFS (Another Union File System) was one of the earliest storage drivers used by Docker, but it has significant limitations and has been deprecated in favor of OverlayFS. This specific error occurs when: - Docker is configured to use AUFS as the storage driver - The underlying filesystem where /var/lib/docker resides is already using OverlayFS - AUFS cannot be "stacked" on top of an overlay filesystem due to technical limitations This situation commonly arises when: - Upgrading from an old Docker installation that used AUFS - The system was originally set up with AUFS but the underlying filesystem changed - Docker configuration files still reference AUFS after a system upgrade - Running Docker inside a container or VM that uses overlay for its root filesystem The overlay2 driver is now the standard and recommended storage driver for all modern Linux distributions. It's more efficient, better maintained, and doesn't have the stacking limitations of AUFS.
First, identify what storage driver Docker is trying to use:
# Check daemon.json for explicit storage driver setting
cat /etc/docker/daemon.json 2>/dev/null
# Check systemd service overrides
systemctl cat docker.service | grep -i storage
# Check for AUFS directories from old installation
ls -la /var/lib/docker/ | grep -E "(aufs|overlay)"If you see "storage-driver": "aufs" in daemon.json, that's the source of the conflict.
Verify what filesystem type /var/lib/docker is using:
# Check filesystem type for Docker data directory
df -T /var/lib/docker
# Or check the mount options
mount | grep -E "(/var/lib/docker|overlay)"
# Check if overlay module is loaded
lsmod | grep overlayIf the filesystem shows as overlay or if your root filesystem uses OverlayFS (common in containers), AUFS cannot work on top of it.
Before making changes, stop Docker and optionally backup your data:
# Stop Docker service
sudo systemctl stop docker
sudo systemctl stop docker.socket
# Backup existing Docker data (optional but recommended)
sudo cp -a /var/lib/docker /var/lib/docker.backup.$(date +%Y%m%d)
# List existing images and containers for reference
# (This won't work if daemon isn't running, but try anyway)
docker images 2>/dev/null > ~/docker-images-backup.txt
docker ps -a 2>/dev/null > ~/docker-containers-backup.txtNote: Switching storage drivers means existing images, containers, and volumes will not be available with the new driver. You'll need to re-pull images and recreate containers.
Update Docker configuration to use the modern overlay2 driver:
# Create or update daemon.json
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<EOF
{
"storage-driver": "overlay2"
}
EOFIf you already have a daemon.json with other settings, edit it to change or add the storage-driver:
sudo nano /etc/docker/daemon.jsonMake sure the JSON is valid - Docker won't start with invalid JSON.
Remove the old AUFS data directory to prevent conflicts:
# Remove AUFS-specific directory
sudo rm -rf /var/lib/docker/aufs
# Optionally, for a clean start, remove all Docker data
# WARNING: This deletes ALL images, containers, and volumes!
# sudo rm -rf /var/lib/docker/*If you want to preserve some data, you can try keeping other directories like volumes/ if they contain bind-mounted data. However, for cleanest results, a fresh start is recommended.
Start Docker and verify the new storage driver is active:
# Reload systemd configuration (in case of changes)
sudo systemctl daemon-reload
# Start Docker
sudo systemctl start docker
# Verify Docker is running
sudo systemctl status docker
# Check the storage driver
docker info | grep -A5 "Storage Driver"You should see:
Storage Driver: overlay2
Backing Filesystem: extfs
Supports d_type: true
Using metacopy: false
Native Overlay Diff: trueSince switching storage drivers makes old data inaccessible, you'll need to restore your containers:
# Pull your required images again
docker pull nginx:latest
docker pull postgres:15
# ... pull other images you need
# If using docker-compose, simply run:
docker-compose pull
docker-compose up -d
# Run a test to verify everything works
docker run --rm hello-worldIf you had containers with important data, restore from your backups or source control (docker-compose files, Dockerfiles, etc.).
Why AUFS is Deprecated:
AUFS (Another Union File System) was one of the first union filesystems used by Docker when it launched in 2013. However, it was never accepted into the mainline Linux kernel due to code quality concerns. This meant:
- Distributions had to maintain separate AUFS patches
- Support varied widely between kernels
- Ubuntu dropped AUFS support around kernel 4.13+
- Debian and other distributions followed
OverlayFS (overlay2) was merged into the Linux kernel in version 3.18, providing a standardized, well-maintained alternative.
AUFS on Overlay Technical Details:
The error "aufs not supported over overlay" is a filesystem stacking limitation. Union filesystems like AUFS and OverlayFS work by layering directories. When AUFS tries to operate on a directory that's already part of an overlay mount, it cannot properly manage the layer metadata because:
1. Overlay changes file attributes in ways AUFS doesn't expect
2. Copy-up operations conflict between the two drivers
3. Inode handling differs between the filesystems
Container-in-Container Scenarios:
This error is particularly common when running Docker inside:
- LXC/LXD containers (which often use overlay for the root filesystem)
- Docker-in-Docker (DinD) setups with overlay storage
- Kubernetes pods using overlay storage for ephemeral storage
For these scenarios, either use overlay2 consistently, or consider using VFS driver (slower but always compatible):
{
"storage-driver": "vfs"
}Migration Script for Large Deployments:
For systems with many images to migrate, consider using docker-save/load:
# Before switching drivers - save critical images
docker save -o /backup/myapp.tar myapp:latest
docker save -o /backup/database.tar postgres:15
# After switching to overlay2 - restore
docker load -i /backup/myapp.tar
docker load -i /backup/database.tarNote: Container data volumes (not bind mounts) cannot be migrated this way.
Checking Kernel Support:
Verify your kernel supports overlay2:
# Check kernel config
grep OVERLAY /boot/config-$(uname -r) 2>/dev/null
# Or for kernels without config file
cat /proc/filesystems | grep overlayYou need CONFIG_OVERLAY_FS=y or =m for overlay2 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