A container cannot write files and reports a read-only file system
read-only file systemShort 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.
Fix it fast
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}}'2Match what you see, then jump to its fix
- 1
root readonly: true, and writes fail on paths such as /tmp, /var/run or /var/cacheThe container was started with --read-onlyFix - 2
Only the mounted path is read-only; the rest of the container is writableA bind mount carries :ro or readonlyFix - 3
You 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
- 1
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-image3Verify
The write that failed now succeeds.
docker exec my-container sh -c 'touch /tmp/probe && echo writable'Confirmed by docs.docker.com
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-image3Verify
Recreate the container and write to the path.
docker exec my-container sh -c 'touch /data/probe && echo writable'Confirmed by docs.docker.com
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-image3Verify
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
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
Servers
docker run or compose cannot mount a host folder that is not there
docker: Error response from daemon: invalid mount config for type "bind": bind source path does not exist: /dev/noexist
A bind mount needs a source folder on the host.
3 causes, each with a fixServers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fixServers
sam local fails: Running AWS SAM projects locally requires Docker
Cannot connect to the Docker daemon. Is the docker daemon running on this host?
sam local start-api and sam local invoke run your function inside a Docker container, so SAM stops if it cannot talk to Docker.
3 causes, each with a fixServers
dnf fails to download repo metadata in a CentOS 8 Docker build
The same Dockerfile built fine before 2022
CentOS Linux 8 reached end of life on 31 December 2021 and its content left the mirrors.
2 causes, each with a fixServers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
Cypress says the npm package is installed but the binary is missing
Cypress binary is missing after npm install in CI or in a Docker build
The npm package is only a launcher.
3 causes, each with a fix