Docker permission denied running as non-root user

What this failure means

A Docker container process running as a non-root user encountered a permission denied error while trying to access files or directories owned by root or another user.

Symptoms

Faultline looks for one or more of these log fragments:

permission denied
cannot open
cannot read
Access denied
Operation not permitted
running as user
uid 1000
chown

Diagnosis

Docker containers often run as non-root for security. Permission denied errors occur when:

• The container runs as a non-root user (e.g., via USER directive in Dockerfile) but tries to access files owned by root.
• File permissions in the image are too restrictive (e.g., chmod 600 instead of 644).
• Mount volumes from the host have the wrong ownership or permissions.
• The application writes to directories it does not own (e.g., /app owned by root).
• The container tries to write to a read-only filesystem.

The error typically appears as permission denied, Cannot write to..., or Operation not permitted.

Fix steps

1. Identify which files or directories the error is accessing:

   docker logs <container-id> | grep "Permission denied"
   

2. Check the file ownership and permissions in the Dockerfile:

   RUN useradd -m -u 1000 appuser
   WORKDIR /app
   COPY --chown=appuser:appuser . .
   USER appuser
   

3. Ensure writable directories are owned by the non-root user:

   RUN mkdir -p /app/logs /app/cache && \
       chown -R appuser:appuser /app/logs /app/cache && \
       chmod 755 /app/logs /app/cache
   USER appuser
   

4. If mounting volumes, ensure consistent permissions:

   # On host before mounting
   sudo chown 1000:1000 /host/path
   sudo chmod 755 /host/path
   
   # In docker run or docker-compose
   docker run -v /host/path:/app/data <image>
   

5. Verify the container starts without permission errors:

   docker run --rm <image>
   

Validation

• docker logs <container-id> shows no “Permission denied” errors.
• The container runs without exiting or crashing.
• Application writes to expected log or data directories successfully.

Why it matters

Running as non-root is a security best practice. Containers that fail due to permission issues either have misconfigured user/file ownership or overly restrictive file permissions.

Prevention

• Create a non-root user in the Dockerfile and set USER.
• Use COPY --chown to set correct ownership during build.
• Document the container’s user and required file permissions in README.md.
• Test containers locally with non-root users before deploying.

Try it locally

docker build -t test .
docker run --rm test
docker run --rm test

How Faultline detects it

Use faultline explain docker-permission-denied-nonroot to see the full playbook.

faultline analyze build.log
faultline explain docker-permission-denied-nonroot

Generated from playbooks/bundled/log/runtime/docker-permission-denied-nonroot.yaml. Do not edit directly.