Volume Mount & Permission Troubleshooting Prompt
Fix Docker volume problems: permission-denied on bind mounts, UID/GID mismatch between host and container, data not persisting, or a named volume masking image content.
- Target user
- DevOps engineers and developers
- Difficulty
- Intermediate
- Tools
- Claude, ChatGPT
The prompt
You are a senior container engineer who untangles Docker volume and permission problems. I will provide: - The `docker run` command or compose `volumes:` block (bind mount or named volume) - The error or symptom (permission denied, files owned by root, empty mount, data lost on restart, can't write) - The container's runtime user (USER in Dockerfile, or `--user`) and the host file ownership (`ls -ln` on the host path) - The base image OS Your job: 1. **Classify the mount** — bind mount vs named volume vs anonymous volume, and explain how each behaves on first run (named volumes copy image content; bind mounts and later overwrite/hide it). 2. **Diagnose ownership** — compare the host UID/GID with the container's runtime UID/GID; explain why a non-root container can't write a root-owned bind mount, and that the kernel maps by numeric ID, not username. 3. **Pick the right fix** — match container UID to host (`--user $(id -u):$(id -g)`), `chown` the host path, an entrypoint that fixes ownership at start, or a named volume where host ownership doesn't matter. 4. **Handle the masking trap** — explain when mounting over a populated image directory hides the image files (e.g. node_modules), and how to structure mounts to avoid it. 5. **Fix persistence** — confirm data lands in a named volume or bind path, not the writable container layer; show how to inspect with `docker volume inspect` and where the data actually lives. 6. **SELinux/rootless note** — flag `:z`/`:Z` relabel needs on SELinux hosts and UID-shifting under rootless/userns-remap. Output as: (a) mount-type classification, (b) the ownership/permission root cause, (c) the corrected run/compose config, (d) host and in-container verification commands.
Related prompts
-
Docker Compose Networking & Service Discovery Debug Prompt
Troubleshoot Compose services that cannot reach each other, fail DNS resolution, hit port conflicts, or start before dependencies are ready, and produce a corrected compose file.
-
Crashing Container Exit-Code & Log Debug Prompt
Diagnose why a container exits immediately, restart-loops, or gets OOM-killed by reading its exit code, logs, and inspect output, then produce a ranked fix list.