OCI runtime create failed: "read-only file system" error in Docker

When working with Docker containers, you may encounter the frustrating "OCI runtime create failed" error with a "read-only file system" message. This error typically indicates permission or configuration issues that prevent Docker from successfully starting your containers.

Understanding the error

The core error message usually looks like this:

ERROR: for backend Cannot start service backend: failed to create shim task:
OCI runtime create failed: runc create failed: unable to start container process: 
error during container init: error mounting [...] to rootfs at "/app/node_modules":
mkdir [...] read-only file system: unknown

This error occurs when Docker's container runtime (runc) cannot create the necessary file system structures due to permission restrictions or configuration conflicts.

Root cause analysis

The error typically happens when:

1. Volume mount conflicts - A named volume and host directory are mounted to the same location
2. Permission issues - The container process lacks write permissions to required directories
3. Resource constraints - Insufficient CPU or memory resources in Kubernetes environments
4. Configuration errors - Incorrect file paths or executable names in Docker commands

Solutions

1. Fix volume mount conflicts

The most common cause is when both a host volume and named volume try to mount to the same directory. In the provided Docker Compose configuration:

# docker-compose.dev.yml
services:
  backend:
    volumes:
      - ./:/app:ro          # Host directory mounted as read-only
      - /app/node_modules   # Named volume for node_modules

This creates a conflict where Docker tries to mount both the host directory (read-only) and a named volume to /app/node_modules.

Solution: Update your volume configuration:

volumes:
  - ./:/app
  - node_modules_data:/app/node_modules

# Define the volume at the bottom
volumes:
  node_modules_data:

2. Adjust file permissions

Linux permission issues can cause read-only file system errors. Add ownership adjustments to your Dockerfile:

FROM node:16-alpine
WORKDIR /app
# ... other instructions ...
RUN chown -R node:node /app
RUN npm install
USER node
CMD ["ts-node", "./src/server.ts"]

This ensures the container process has proper ownership of the application directory.

3. Recreate containers and clean resources

Docker containers can become corrupted over time. Clean up and restart:

# Stop and remove containers
docker-compose down

# Remove dangling images, containers, and networks
docker system prune

# Remove specific volumes (be cautious with this)
docker volume prune

# Rebuild and start fresh
docker-compose up -d --build

4. Verify executable paths and names

Ensure your commands reference existing executables:

# Before (may fail if python doesn't exist)
command: python manage.py runserver 0.0.0.0:8000

# After (use the correct executable name)
command: python3 manage.py runserver 0.0.0.0:8000

5. Adjust resource allocations (Kubernetes)

In Kubernetes environments, resource constraints can cause similar errors:

# deployment.yml - adjust resources if needed
resources:
  limits:
    cpu: "600m"
    memory: "1024Mi"
  requests:
    cpu: "100m"
    memory: "500Mi"

Best practices to prevent errors

1. Use explicit volume definitions instead of anonymous volumes
2. Set proper file permissions in your Dockerfile
3. Regularly clean up unused Docker resources
4. Verify executable paths in your container commands
5. Test resource requirements before deploying to production

WARNING

Be cautious with docker system prune and docker volume prune as these commands remove all unused resources, which might include volumes containing important data.

Conclusion

The "OCI runtime create failed" error with "read-only file system" typically stems from permission issues or volume configuration conflicts. By understanding Docker's volume mounting system and ensuring proper file permissions, you can resolve these issues and maintain stable container environments.

For development setups, the most effective solution is often to:

1. Fix volume conflicts in docker-compose.yml
2. Add proper permission settings in your Dockerfile
3. Clean up and rebuild your containers

These steps will help you overcome the read-only file system error and ensure your Docker containers start successfully.