This error occurs when a Docker container requires elevated privileges to access host resources, devices, or kernel capabilities that are restricted by default. The solution involves either running with --privileged flag or, preferably, granting only the specific capabilities needed.
When you run a Docker container, it operates in a sandboxed environment with limited access to the host system's resources. This isolation is a core security feature of containers. The Docker daemon enforces restrictions through Linux capabilities, cgroups, and security modules like SELinux or AppArmor. This error appears when your container attempts to perform an operation that requires elevated privileges, such as: - Accessing hardware devices directly (e.g., /dev/sda, USB devices) - Modifying kernel parameters or loading kernel modules - Running Docker-in-Docker (DinD) scenarios - Performing network-level operations that require raw socket access - Mounting file systems or using loop devices The Docker daemon detects that the requested operation cannot be completed with the container's current privilege level and returns this error to indicate that privileged mode is required.
Before enabling privileged mode, determine exactly what capability or access your container requires. Running in privileged mode gives the container nearly full host access, which is a significant security risk.
Check the container logs or application documentation to understand the specific operation that's failing:
docker logs <container_name>Common operations that trigger this error include:
- Device access (USB, GPU, storage devices)
- Network packet capture (tcpdump, Wireshark)
- Kernel module operations
- Docker-in-Docker builds
Instead of granting full privileged access, add only the specific Linux capabilities your container needs using the --cap-add flag:
# For network administration (iptables, routing)
docker run --cap-add=NET_ADMIN myimage
# For raw network access (packet capture)
docker run --cap-add=NET_RAW myimage
# For system administration tasks
docker run --cap-add=SYS_ADMIN myimage
# Multiple capabilities
docker run --cap-add=NET_ADMIN --cap-add=SYS_PTRACE myimageCommon capabilities:
| Capability | Use Case |
|------------|----------|
| NET_ADMIN | Network interface configuration, iptables |
| NET_RAW | Raw sockets, packet capture |
| SYS_ADMIN | Mount operations, system calls |
| SYS_PTRACE | Debugging, tracing processes |
| SYS_MODULE | Loading kernel modules |
If your container needs access to specific devices, use the --device flag instead of privileged mode:
# Access a specific device
docker run --device=/dev/sda:/dev/sda myimage
# Access USB devices
docker run --device=/dev/bus/usb:/dev/bus/usb myimage
# Access GPU (NVIDIA)
docker run --device=/dev/nvidia0:/dev/nvidia0 myimageThis approach is more secure because it only exposes the specific devices needed rather than all host devices.
If specific capabilities and device access aren't sufficient, you can run in privileged mode:
docker run --privileged myimageFor Docker Compose, add it under the service definition:
version: '3.8'
services:
myservice:
image: myimage
privileged: trueWarning: This grants the container almost all capabilities of the host machine. Only use this with trusted images and when absolutely necessary.
For Docker-in-Docker scenarios (common in CI/CD), you have several options:
Option 1: Use --privileged (simple but less secure)
docker run --privileged -v /var/run/docker.sock:/var/run/docker.sock docker:dindOption 2: Mount Docker socket (shares host Docker daemon)
docker run -v /var/run/docker.sock:/var/run/docker.sock docker:latestOption 3: Use rootless Docker or Podman
Consider alternatives like rootless Docker or Podman which don't require privileged mode for nested container operations.
If you're running on Kubernetes or Docker Swarm, privileged containers may be restricted by security policies.
For Kubernetes:
apiVersion: v1
kind: Pod
metadata:
name: privileged-pod
spec:
containers:
- name: mycontainer
image: myimage
securityContext:
privileged: trueYou may also need to configure PodSecurityPolicy or PodSecurityStandards to allow privileged containers.
For Docker Swarm:
Privileged mode is not supported in Swarm mode for security reasons. Consider using capabilities or running standalone containers for tasks requiring elevated privileges.
Security Implications of Privileged Mode:
Running a container with --privileged is essentially equivalent to giving it root access to the host system. The container can:
- Access all devices on the host
- Escape the container and access the host filesystem
- Load kernel modules
- Modify network configuration
- Potentially compromise other containers
This makes privileged containers a significant security risk, especially with untrusted images.
Best Practices:
1. Always start with the principle of least privilege
2. Use --cap-add for specific capabilities instead of --privileged
3. Use --device for specific device access
4. Audit images before running them in privileged mode
5. Consider using Podman's rootless mode as an alternative
6. Implement security policies in orchestration platforms to restrict privileged containers
SELinux and AppArmor:
On systems with SELinux or AppArmor enabled, even with --privileged, some operations may still be restricted. You may need to:
# Disable SELinux labels for the container
docker run --privileged --security-opt label=disable myimage
# Disable AppArmor for the container
docker run --privileged --security-opt apparmor=unconfined myimageWindows Considerations:
Windows containers do not support privileged mode. If you see this error on Windows, you may need to:
- Switch to Linux containers mode
- Use a different approach for the operation you're attempting
- Run a Linux VM for tasks requiring privileged access
Debugging Capability Requirements:
To discover what capabilities your application actually needs, you can:
1. Run with --privileged initially
2. Use tools like ausearch (SELinux) or capsh to audit required capabilities
3. Progressively remove capabilities until you find the minimum set needed
image operating system "linux" cannot be used on this platform
How to fix 'image operating system linux cannot be used on this platform' in Docker
manifest unknown: manifest unknown
How to fix 'manifest unknown' in Docker
cannot open '/etc/passwd': Permission denied
How to fix 'cannot open: Permission denied' in Docker
Error response from daemon: failed to create the ipvlan port
How to fix 'failed to create the ipvlan port' in Docker
toomanyrequests: Rate exceeded for anonymous users
How to fix 'Rate exceeded for anonymous users' in Docker Hub