# failed to mount overlay: permission denied

- **ID:** `docker/overlay2-mount-permission-denied`
- **Domain:** docker
- **Category:** system_error
- **Verification:** ai_generated
- **Fix Rate:** 75%

## Root Cause

The Docker overlay2 storage driver cannot mount due to insufficient kernel capabilities or SELinux/AppArmor restrictions, often after a kernel update.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| Docker 24.0.7 | active | — | — |
| Docker 25.0.0 | active | — | — |
| Kernel 6.5.0 | active | — | — |

## Workarounds

1. **Check SELinux context and set boolean: sudo setsebool -P container_manage_cgroup 1** (85% success)
   ```
   Check SELinux context and set boolean: sudo setsebool -P container_manage_cgroup 1
   ```
2. **Switch Docker storage driver to overlay (legacy) or devicemapper as fallback: edit /etc/docker/daemon.json and add 'storage-driver': 'overlay' then restart docker.** (70% success)
   ```
   Switch Docker storage driver to overlay (legacy) or devicemapper as fallback: edit /etc/docker/daemon.json and add 'storage-driver': 'overlay' then restart docker.
   ```
3. **If using AppArmor, check apparmor_status and ensure docker profile is loaded: sudo aa-status | grep docker** (80% success)
   ```
   If using AppArmor, check apparmor_status and ensure docker profile is loaded: sudo aa-status | grep docker
   ```

## Dead Ends

- **sudo systemctl restart docker** — Restarting docker daemon alone does not fix the underlying filesystem or security context issue. (80% fail)
- **sudo apt-get remove docker && sudo apt-get install docker** — Reinstalling Docker does not address kernel or SELinux configuration changes. (70% fail)
- **setenforce 0** — Disabling SELinux entirely is overkill and may have security implications, but it works temporarily; however, it's not a permanent fix. (50% fail)