Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

A container cannot write files and reports a read-only file system

Errorread-only file system

Short answer

Docker only makes a path read-only when told to. Three settings do it: --read-only on the container, a :ro or readonly flag on a bind mount, and a read-only parent mount that also makes submounts read-only on kernel 5.12 or later. Find which one covers the path you write to, then give that path a writable volume or tmpfs.

  • Applies to Docker Engine 28, Linux kernel 6.x
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Inspect the container's mounts and the read-only flag on its root file system, then compare with the path that fails.

    docker inspect my-container --format 'root readonly: {{.HostConfig.ReadonlyRootfs}}'
    docker inspect my-container --format '{{json .Mounts}}'
  2. 2Match what you see, then jump to its fix

    1. 1root readonly: true, and writes fail on paths such as /tmp, /var/run or /var/cacheThe container was started with --read-onlyFix
    2. 2Only the mounted path is read-only; the rest of the container is writableA bind mount carries :ro or readonlyFix
    3. 3You mounted a parent directory read-only and a nested mount inside it is read-only tooThe path is a submount of a read-only bind mountFix

What does the error look like?

  • read-only file system

Cause 1 of 3

The container was started with --read-only

1Check

--read-only mounts the container's root file system read-only, so a process can only write to volumes you provide.

docker inspect my-container --format '{{.HostConfig.ReadonlyRootfs}}'

2Fix

Keep --read-only if you want it, and give the program a writable place: a volume, or a tmpfs for scratch paths.

docker run --read-only --tmpfs /tmp --tmpfs /run -v app-data:/data my-image

3Verify

The write that failed now succeeds.

docker exec my-container sh -c 'touch /tmp/probe && echo writable'

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

A bind mount carries :ro or readonly

1Check

Bind mounts are read-write unless the option list contains readonly or ro (--mount), or ro as the third field of -v. Look at the RW flag of each mount in the inspect output.

docker inspect my-container --format '{{range .Mounts}}{{.Destination}} rw={{.RW}}{{println}}{{end}}'

2Fix

Remove the ro option from the mount of the path that needs writes.

# before
docker run -v "$PWD/data:/data:ro" my-image
# after
docker run -v "$PWD/data:/data" my-image

3Verify

Recreate the container and write to the path.

docker exec my-container sh -c 'touch /data/probe && echo writable'

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

The path is a submount of a read-only bind mount

1Check

Submounts inside a bind mount are included by default. When the parent is read-only, Docker makes the submounts read-only as well on a best-effort basis, which needs Linux kernel 5.12 or later; older kernels leave them writable.

uname -r
docker inspect my-container --format '{{json .Mounts}}'

2Fix

Mount the nested directory on its own as a writable mount, or choose the bind-recursive option: writable keeps submounts writable. The option exists only with --mount.

docker run --mount type=bind,src="$PWD/project",dst=/project,readonly,bind-recursive=writable my-image

3Verify

Write into the nested path from the container.

docker exec my-container sh -c 'touch /project/sub/probe && echo writable'

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • When you turn on --read-only, list the paths the program writes to (temp, pid, cache) and give each a tmpfs or a volume from the start.
  • Use ro only on mounts that really are read-only inputs, such as config files.
  • Prefer --mount for bind mounts: the option names make read-only settings visible in review.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.