How to fix Read-only file system in Docker

DockerINTERMEDIATEMEDIUM

This error occurs when Docker tries to write to a filesystem that is mounted as read-only. Common causes include Snap installations, disk space issues, hardware failures, intentional read-only mounts, and volume permission conflicts.

What this error means

The "Read-only file system" error in Docker indicates that a write operation failed because the target filesystem doesn't allow modifications. This can happen at multiple levels: the Docker daemon storage, container filesystem, or mounted volumes. When Docker reports this error, it means one of these scenarios is occurring: 1. The Docker daemon itself cannot write to its storage directory (usually /var/lib/docker) 2. A container is trying to write to a path that's mounted with read-only permissions 3. The underlying host filesystem has become read-only due to hardware issues or system protection 4. The container is running with the --read-only flag On Linux systems, a filesystem can transition to read-only mode automatically when the kernel detects I/O errors or filesystem corruption. This is a protective measure to prevent data loss. Docker installed via Snap also runs in a sandboxed environment where the host filesystem appears read-only.

How to fix "Read-only file system"

1Check if Docker is installed via Snap

On Ubuntu, Docker installed via Snap has restricted filesystem access. Verify your installation method:

bash

# Check if Docker is a snap package
which docker
# If output is /snap/bin/docker, it's a Snap installation

snap list | grep docker

If Docker is installed via Snap, the host OS appears read-only to Docker. You have two options:
1. Use Snap-compatible paths: /home, /var/snap/docker
2. Reinstall Docker from the official repository (recommended)

bash

# Remove Snap Docker
sudo snap remove docker

# Install from official Docker repository
# Follow: https://docs.docker.com/engine/install/ubuntu/

2Check available disk space

A full disk can cause the filesystem to remount as read-only. Check disk usage:

bash

# Check overall disk usage
df -h

# Check Docker-specific disk usage
docker system df

# Check /var/lib/docker specifically
du -sh /var/lib/docker/*

If disk space is low:

bash

# Remove unused Docker resources
docker system prune -a --volumes

# Remove stopped containers
docker container prune

# Remove unused images
docker image prune -a

# Remove unused volumes (WARNING: data loss)
docker volume prune

After freeing space, restart Docker:

bash

sudo systemctl restart docker

3Check for filesystem errors in system logs

Hardware issues can cause the kernel to remount filesystems as read-only. Check system logs:

bash

# Check for filesystem errors
dmesg | grep -i "read.only\|EXT4-fs error\|I/O error\|aborting journal"

# Check journalctl for Docker-related filesystem issues
journalctl -u docker --since "1 hour ago" | grep -i "read.only\|error"

If you see errors like:
- "EXT4-fs error" or "Aborting journal on device"
- "I/O error" or "Buffer I/O error"
- "Remounting filesystem read-only"

This indicates hardware failure. Immediate action required:
1. Backup important data immediately
2. Run filesystem check: sudo fsck -y /dev/sdX (replace with your device)
3. Consider replacing the storage device

4Check if mount is read-only and remount

Verify the mount status and remount if needed:

bash

# Check if /var/lib/docker is on a read-only mount
mount | grep "$(df /var/lib/docker | tail -1 | awk '{print $1}')"
# Look for "ro" in the output

# Check the specific directory
cat /proc/mounts | grep docker

If mounted as read-only, try remounting:

bash

# Remount as read-write (replace /dev/sdX with your device)
sudo mount -o remount,rw /

# Or for a specific mount point
sudo mount -o remount,rw /var/lib/docker

Note: If remounting fails, it usually indicates hardware issues or filesystem corruption.

5Check container read-only settings

If the error occurs inside a container, check if it's running in read-only mode:

bash

# Check if container has read-only root filesystem
docker inspect CONTAINER_NAME | grep -i "readonly"

If you're using docker-compose, check for read-only settings:

yaml

# docker-compose.yml
services:
  myservice:
    image: myimage
    read_only: true  # This makes the container filesystem read-only
    # Or in volumes:
    volumes:
      - ./data:/app/data:ro  # :ro means read-only

To fix, either:
1. Remove read_only: true from compose file
2. Change :ro to :rw on volume mounts
3. Use tmpfs for directories that need to be writable:

yaml

services:
  myservice:
    read_only: true
    tmpfs:
      - /tmp
      - /var/run

6Resolve conflicting volume mount permissions

Volume mount conflicts can cause read-only errors. This happens when a parent directory is read-only but a child needs write access:

yaml

# Problematic configuration
volumes:
  - ./config:/app/config:ro      # Parent is read-only
  - ./config/cache:/app/config/cache:rw  # Child needs write - CONFLICT

Fix: Don't mark parent directories as read-only if children need write access:

yaml

# Solution 1: Remove read-only from parent
volumes:
  - ./config:/app/config
  - ./config/cache:/app/config/cache

# Solution 2: Use separate, non-nested paths
volumes:
  - ./config:/app/config:ro
  - ./cache:/app/cache  # Different path, no conflict

7Fix Docker Desktop issues (macOS/Windows)

On Docker Desktop, the Docker VM can become corrupted:

Try restarting Docker Desktop:
1. Right-click Docker icon in system tray/menu bar
2. Select "Restart"

If restart doesn't work, reset the Docker VM:

On Windows:

powershell

# Stop Docker Desktop
# Delete the VM state
Remove-Item "$env:APPDATA\Docker\*" -Recurse -Force
# Restart Docker Desktop

On macOS:

bash

# Delete Docker Desktop data (WARNING: removes all containers/images)
rm -rf ~/Library/Containers/com.docker.docker
rm -rf ~/Library/Group\ Containers/group.com.docker
# Restart Docker Desktop

Docker Desktop version issues:
Some versions have bugs causing this error. If you recently updated:
1. Downgrade to a previous stable version
2. Check Docker Desktop release notes for known issues

8Handle build-time bind mount restrictions

During docker build, bind mounts are read-only by default. If your build fails when trying to write to a mounted directory:

dockerfile

# This mount is read-only by default
RUN --mount=type=bind,source=.,target=/src cp /src/file /app/

Solutions:

1. Use rw option (written data is discarded after build):

dockerfile

RUN --mount=type=bind,source=.,target=/src,rw cp /src/file /app/

2. Use cache mounts for persistent build data:

dockerfile

RUN --mount=type=cache,target=/root/.cache pip install -r requirements.txt

3. Use --output to export files from the build:

bash

docker build --output=type=local,dest=./output .

4. Copy files in Dockerfile instead of mounting:

dockerfile

COPY . /src
RUN cp /src/file /app/

9Restart Docker daemon and verify

After making changes, restart Docker and verify the fix:

bash

# Restart Docker daemon
sudo systemctl restart docker

# Wait for Docker to be ready
sleep 5

# Verify Docker is working
docker info

# Test write capability
docker run --rm alpine sh -c "touch /test && echo 'Write test passed'"

If the issue persists, check Docker logs:

bash

# View Docker daemon logs
sudo journalctl -u docker -f

# On Docker Desktop, check from GUI:
# Settings > Troubleshoot > View logs

How to fix Read-only file system in Docker

What this error means

Typical symptoms

Common causes

How to fix "Read-only file system"

Advanced notes

Related errors

Official resources & further reading