Docker Compose "read-only file system" on a Volume Mount in CI

A container tried to write to a mount that was set up read-only. Compose mounted the volume with :ro (or the service runs with a read-only root filesystem), so any write is rejected by the kernel.

What this error means

A service starts but fails at runtime with Read-only file system when it writes to a mounted path. The container is healthy until it attempts the first write into the read-only mount.

OSError: [Errno 30] Read-only file system: '/app/cache/index.lock'
# /app/cache is mounted "- ./cache:/app/cache:ro" in docker-compose.yml

Common causes

The volume is mounted with the :ro flag

A - ./cache:/app/cache:ro entry mounts the path read-only. The container can read it but any write fails with "Read-only file system".

The service has read_only: true

A service configured with read_only: true makes its entire root filesystem read-only, so writes outside an explicit writable volume/tmpfs fail.

The host path itself is read-only

A bind source on a read-only host filesystem (or a squashed/immutable mount) cannot be written through even without :ro.

How to fix it

Drop :ro for paths the service must write

Mount the volume read-write where the container needs to write into it.

services:
  app:
    volumes:
      - ./cache:/app/cache        # read-write (no :ro)
      - ./config:/app/config:ro   # keep :ro only where writes aren't needed

Add a writable tmpfs/volume under a read-only root

With read_only: true, give the writable directories explicit tmpfs or named volumes.

services:
  app:
    read_only: true
    tmpfs:
      - /tmp
    volumes:
      - appdata:/app/data        # writable named volume
volumes:
  appdata:

How to prevent it

• Mount only genuinely-immutable paths with :ro.
• When using read_only: true, declare writable tmpfs/volumes for paths the app writes.
• Confirm bind sources sit on a writable host filesystem.

Related guides