This error occurs when Docker attempts to use the overlay2 storage driver on an XFS filesystem that was formatted without d_type (directory entry type) support. The XFS filesystem must be formatted with ftype=1 to enable d_type support required by overlay2.
The overlay2 storage driver is Docker's default and recommended storage driver for managing container images and layers. It relies on a Linux kernel feature called d_type (directory entry type) to efficiently track file types within directories. When an XFS filesystem is created, it can optionally include d_type support via the `ftype` parameter. If `ftype=0` (the default on older CentOS 7 installations), the filesystem lacks d_type support, and Docker's overlay2 driver cannot function correctly. This error indicates that: - Docker is configured to use overlay2 (either explicitly or by default) - The backing filesystem at /var/lib/docker is XFS - That XFS filesystem was formatted without d_type support (ftype=0) - Docker v23.0+ now refuses to start in this configuration (previously it was just a warning) This is particularly common on CentOS 7 systems where the installer historically defaulted to XFS without ftype=1.
First, verify whether your XFS filesystem supports d_type by checking the ftype parameter:
# Check the XFS filesystem where Docker data is stored
xfs_info /var/lib/docker
# Or check the root filesystem if Docker uses it
xfs_info /Look at the output for the ftype value in the naming section (typically line 6):
- ftype=1 - d_type is enabled, overlay2 should work
- ftype=0 - d_type is disabled, this is your problem
You can also check via Docker (on older versions that still start):
docker info | grep "Supports d_type"Confirm the filesystem type for Docker's data directory:
# Check filesystem type and mount options
df -T /var/lib/docker
# Check all XFS filesystems
mount | grep xfs
# Check which device hosts /var/lib/docker
findmnt /var/lib/dockerIf /var/lib/docker is on the root partition, you'll need to either reformat the root filesystem (destructive) or move Docker's data to a new partition.
The recommended solution is to create a new XFS filesystem with d_type support and use it for Docker data.
Warning: This approach requires reformatting. Back up any important Docker images first.
# Stop Docker
sudo systemctl stop docker
# Back up existing Docker data (optional, if you have images to save)
sudo mv /var/lib/docker /var/lib/docker.bak
# Identify a disk or partition to use (example: /dev/sdb1)
# Create XFS filesystem WITH ftype=1
sudo mkfs.xfs -n ftype=1 /dev/sdb1
# Create mount point and mount
sudo mkdir -p /var/lib/docker
sudo mount /dev/sdb1 /var/lib/docker
# Add to /etc/fstab for persistence
echo '/dev/sdb1 /var/lib/docker xfs defaults 0 0' | sudo tee -a /etc/fstab
# Start Docker
sudo systemctl start dockerIf you cannot add a new disk, create a loopback device with a properly formatted XFS filesystem:
# Stop Docker
sudo systemctl stop docker
# Create a file to use as the backing store (adjust size as needed)
sudo dd if=/dev/zero of=/docker-storage.img bs=1G count=50
# Create XFS filesystem with ftype=1
sudo mkfs.xfs -n ftype=1 /docker-storage.img
# Back up and remove old Docker data
sudo mv /var/lib/docker /var/lib/docker.bak
# Mount the loopback device
sudo mkdir -p /var/lib/docker
sudo mount -o loop /docker-storage.img /var/lib/docker
# Add to /etc/fstab
echo '/docker-storage.img /var/lib/docker xfs loop 0 0' | sudo tee -a /etc/fstab
# Start Docker
sudo systemctl start dockerThe ext4 filesystem natively supports d_type and works well with overlay2:
# Stop Docker
sudo systemctl stop docker
# Back up existing Docker data
sudo mv /var/lib/docker /var/lib/docker.bak
# Format partition with ext4 (example: /dev/sdb1)
sudo mkfs.ext4 /dev/sdb1
# Mount the new filesystem
sudo mkdir -p /var/lib/docker
sudo mount /dev/sdb1 /var/lib/docker
# Add to /etc/fstab
echo '/dev/sdb1 /var/lib/docker ext4 defaults 0 0' | sudo tee -a /etc/fstab
# Start Docker
sudo systemctl start dockerThis is often the simplest solution if you're not specifically tied to XFS.
As a temporary workaround, you can configure Docker to use a different storage driver. Note that devicemapper is deprecated and will be removed in future Docker versions:
# Stop Docker
sudo systemctl stop docker
# Configure Docker to use devicemapper (deprecated, temporary workaround only)
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<EOF
{
"storage-driver": "devicemapper"
}
EOF
# Remove old Docker data (required when changing storage drivers)
sudo rm -rf /var/lib/docker/*
# Start Docker
sudo systemctl start dockerWarning: This is not a long-term solution. The devicemapper driver is deprecated and performs worse than overlay2. Plan to migrate to a properly formatted filesystem.
After applying one of the fixes, verify Docker is functioning:
# Check Docker daemon status
sudo systemctl status docker
# Verify storage driver and d_type support
docker info | grep -E "Storage Driver|Backing Filesystem|Supports d_type"
# Run a test container
docker run --rm hello-worldExpected output should show:
Storage Driver: overlay2
Backing Filesystem: xfs
Supports d_type: trueIf you previously saved Docker images before the migration, you can restore them:
# If you saved images using docker save
docker load < my-images-backup.tar
# If you need to re-pull images from a registry
docker pull your-image:tagFor containers with persistent volumes, ensure volume data was properly backed up and restore it to the appropriate location.
Why d_type Matters:
The d_type (directory entry type) feature allows the filesystem to store file type information directly in directory entries, rather than requiring an additional inode lookup. Overlay2 relies on this for efficient layer management. Without it, Docker would experience incorrect behavior when determining whether items are files or directories.
CentOS 7 / RHEL 7 History:
The CentOS 7 installer historically created XFS filesystems without ftype=1. This was because d_type support in XFS was relatively new when CentOS 7 was released. Newer installers (CentOS 8+, RHEL 8+) default to ftype=1.
Docker Version Changes:
- Docker < 23.0: Printed a warning but still attempted to use overlay2
- Docker 23.0+: Fails to start entirely, treating this as a fatal error
- This change was made because running without d_type support caused data corruption
Checking ftype on Existing Filesystems:
You cannot change ftype on an existing XFS filesystem. The only options are:
1. Create a new filesystem with ftype=1
2. Use a different filesystem type (ext4, btrfs)
3. Use a different storage driver (temporary workaround)
Quota Support with XFS:
If you need Docker storage quotas on XFS, the filesystem must also be mounted with the pquota mount option:
mount -o pquota /dev/sdb1 /var/lib/dockerVirtual Environments:
In cloud VMs or containers, the underlying storage may be on XFS without ftype support. Check with your provider or consider using block storage with a properly formatted filesystem.
Bitbucket Pipelines / CI Systems:
This error commonly appears in CI/CD systems running on older infrastructure. Contact your CI provider or use self-hosted runners with properly configured storage.
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