Docker "mkdir /var/lib/docker: read-only file system" in CI

By Kaveh Alemi·Latchkey

The daemon stores images, layers, and container state under its data-root (default /var/lib/docker). If that path lands on a read-only mount - a read-only root filesystem, a remounted volume, or a misconfigured data-root - the daemon cannot create directories and fails with read-only file system.

What this error means

A pull, build, or run fails with Error response from daemon: mkdir /var/lib/docker/...: read-only file system. The data-root is on a read-only mount.

Error response from daemon: error creating overlay mount to /var/lib/docker/overlay2/.../merged: mkdir /var/lib/docker/overlay2: read-only file system

Common causes

A read-only root filesystem

On hardened or immutable hosts, /var/lib/docker may sit on a read-only root, blocking writes.

A misconfigured or remounted data-root

A data-root pointed at a read-only volume cannot store image and container data.

How to fix it

Point data-root at a writable path

1. Set the daemon data-root to a writable mount and restart.

# /etc/docker/daemon.json
{ "data-root": "/mnt/docker-data" }
# then: sudo systemctl restart docker

Remount the data-root read-write

1. If the existing mount should be writable, remount it rw.

mount | grep /var/lib/docker
sudo mount -o remount,rw /var/lib/docker

How to prevent it

• Keep the daemon data-root on a writable mount.
• Avoid placing /var/lib/docker on a read-only root.
• Verify mount options when provisioning Docker hosts.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation