Verified Production Fix
[docker/cli] docker-ce 29.0.0 with nested overlayfs storage driver seems not support whiteout (deleting file on lower layer) in improper dind setup
GH-docker/cli#6646 • Mar 07, 2026
### ROOT CAUSE
The issue arises because Docker's nested overlayfs storage driver does not correctly handle the whiteout functionality when running in a Docker-in-Docker (DinD) setup. This leads to Docker being unable to delete files in the lower layers of the image, causing the build to fail when attempting to remove files like `/etc/hostname`.
### CODE FIX
To resolve this issue, you can adjust the Docker daemon configuration to explicitly set the storage driver and ensure proper compatibility between the outer and inner Docker instances. Here are the steps to fix the issue:
1. **Modify the Docker Daemon Configuration:**
- Create or update the Docker daemon configuration file at `/etc/docker/daemon.json` with the following content to force the use of the `overlay2` driver, which is more reliable:
json
{
"storage-driver": "overlay2"
}
2. **Restart the Docker Service:**
- After updating the configuration, restart the Docker service to apply the changes:
bash
sudo systemctl restart docker
3. **Reinstall Docker (if necessary):**
- If the issue persists, it might be due to a known bug in Docker 29.0.0. Consider updating to a newer stable version:
bash
# Remove the old Docker package
sudo apt-get purge docker-ce docker-daemon docker-docker1 docker-engine docker-engine-docker1 docker-engine-snapshotd docker-snapshotd
# Add the GPG key and repository (if not already done)
sudo curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian bullseye stable" | sudo tee /etc/apt/sources.list.d/docker.list
# Update the package index
sudo apt-get update
# Install the latest Docker CE
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
4. **Verify the Setup:**
- Ensure that both the outer and inner Docker instances are using the same storage driver by checking their configurations and logs.
By forcing Docker to use the `overlay2` storage driver and ensuring that the setup is consistent across both outer and inner Docker environments, the whiteout functionality should work as expected, allowing files to be deleted properly during image builds.
Deploy with DigitalOcean
Use this fix in production instantly. Claim your $200 developer credit.
Get Started →
digital