Fix Docker Image Layer Corruption in 3 Steps

You're in the middle of a build, and suddenly you see "layer corruption" or "failed to get layer" or something about the overlay2 driver. Yeah, it sucks. Let's fix it fast.

The Fast Fix: Prune Everything and Rebuild

Don't try to fix individual layers. The real fix is to wipe the corrupt layers and start fresh. Here's what to do:

Stop all running containers (if any):
```
docker stop $(docker ps -aq)
```
After running this, check with docker ps — you should see no running containers.
Remove all containers, images, and volumes (this is the nuclear option, but it works):
```
docker system prune -a --volumes
```
It will ask for confirmation. Type y and press Enter. You'll see a list of what got removed. Expect something like "Total reclaimed space: 2.5 GB".
Restart the Docker daemon (this clears any stuck internal state):
```
sudo systemctl restart docker
```
Wait 5 seconds. Then check with sudo systemctl status docker — you should see "active (running)".
Rebuild your images from scratch (no cache):
```
docker build --no-cache -t your-image-name .
```
This forces Docker to download all layers fresh. You might see it pull layers one by one. That's normal.

After that, your containers should run fine. Test by running docker run your-image-name.

Why This Works

Docker stores image layers in the /var/lib/docker/overlay2/ directory. This is a union filesystem. What is a union filesystem? It's a way to stack multiple read-only layers on top of each other, and then add a thin writable layer on top. When you run a container, Docker combines these layers into one view.

Layer corruption happens when one of those layers gets written incorrectly. Common causes:

Hard shutdown (power loss while Docker was writing a layer).
Disk full during an image pull or build.
NFS or network storage — Docker doesn't handle network drives well for the overlay2 driver.

The docker system prune -a command removes every layer and every image. Then restarting the daemon clears any in-memory corruption. Rebuilding with --no-cache forces Docker to download fresh layers from the registry, skipping any corrupt local copies.

I've seen this fix work on Ubuntu 20.04, CentOS 7, and even RHEL 8. It's the same process across all Linux distros.

Less Common Variations

Sometimes the full prune is too aggressive. Maybe you can't rebuild because you don't have the Dockerfile anymore. Here are a couple of targeted fixes:

Variation 1: Single Image Corruption

If only one image is corrupt (you get the error only when running that specific image), try removing just that image:

docker rmi your-image-name:tag

Then pull it again:

docker pull your-image-name:tag

If the pull fails too, the registry itself might have a corrupt layer. In that case, you need a different version of the image.

Variation 2: Daemon Won't Start

If sudo systemctl restart docker fails, the corruption might be in the daemon's internal database. Try:

sudo systemctl stop docker
sudo rm -rf /var/lib/docker
sudo systemctl start docker

Warning: This deletes all images and containers. Only do this if you're desperate. After this, you'll need to pull or rebuild everything.

Variation 3: Specific Layer Error During Pull

You see "error getting layer" with a specific hash. This means the local cache has a bad file. Go to /var/lib/docker/overlay2/ and find the folder with that hash (or part of it). Delete it:

sudo find /var/lib/docker/overlay2 -name "*hash*" -exec rm -rf {} \;

Then restart Docker and pull again. This is a surgical option, but it's risky — you might delete the wrong thing if you're not careful.

Prevention

The best way to avoid layer corruption is to not let it happen in the first place. Here's what I do:

Keep Docker updated. Old versions had more bugs with the overlay2 driver. I run sudo apt update && sudo apt upgrade -y docker-ce every month.
Don't fill your disk. Docker needs free space to write layers. I keep at least 10% free on /var/lib/docker.
Avoid NFS for Docker storage. If you must use network storage, switch to the devicemapper driver or use a dedicated Docker volume plugin that supports NFS properly.
Use a UPS. Hard shutdowns are the #1 cause of corruption. A $50 uninterruptible power supply can save you hours of debugging.
Run periodic prunes. I schedule docker system prune -f every Sunday night via cron. It removes unused images and layers before they can accumulate and get corrupted.

Layer corruption is ugly, but it's not permanent. Prune, restart, rebuild. You'll be back up in 10 minutes.