This error occurs when Docker's user namespace remapping feature (userns-remap) is enabled but the host kernel doesn't support user namespaces, or required configuration files are missing. The fix involves enabling kernel support for user namespaces and properly configuring the /etc/subuid and /etc/subgid files.
User namespace remapping is an advanced Docker security feature that isolates container root users from the host's root user. When enabled, container processes running as root (UID 0) are mapped to an unprivileged high-numbered UID on the host, preventing privilege escalation attacks. This error appears because: - The Linux kernel on your host does not have user namespace support enabled - The required configuration files (`/etc/subuid` and `/etc/subgid`) are missing or misconfigured - The Docker daemon is configured to use userns-remap, but the system cannot support it - On older systems like CentOS 7 or RHEL 7, user namespaces are disabled by default in the kernel The Docker daemon checks for user namespace support at startup. If you've added `"userns-remap": "default"` or similar to your `/etc/docker/daemon.json`, Docker will fail to start containers if the host cannot provide this isolation mechanism.
First, verify whether your kernel supports user namespaces:
cat /proc/sys/user/max_user_namespacesIf this returns 0 or the file doesn't exist, user namespaces are disabled. You can also check:
cat /boot/config-$(uname -r) | grep CONFIG_USER_NSLook for CONFIG_USER_NS=y. If it shows # CONFIG_USER_NS is not set, your kernel doesn't support this feature.
On CentOS 7 and RHEL 7, user namespaces are disabled by default. Enable them with these commands:
# Add kernel boot parameters
sudo grubby --args="namespace.unpriv_enable=1 user_namespace.enable=1" --update-kernel="$(grubby --default-kernel)"
# Increase the user namespace limit
echo "user.max_user_namespaces=15000" | sudo tee -a /etc/sysctl.conf
# Apply sysctl changes immediately (or reboot)
sudo sysctl -pA reboot is required for the kernel parameters to take effect:
sudo rebootOn modern systems, user namespaces are usually enabled but may be limited. Check and increase the limit:
# Check current limit
sysctl user.max_user_namespaces
# If it's 0, enable user namespaces
echo "user.max_user_namespaces=28633" | sudo tee /etc/sysctl.d/99-userns.conf
sudo sysctl --systemOn some Ubuntu systems with AppArmor restrictions:
# Check if unprivileged user namespaces are restricted
cat /proc/sys/kernel/unprivileged_userns_clone
# If 0, enable it
echo 1 | sudo tee /proc/sys/kernel/unprivileged_userns_cloneThe /etc/subuid and /etc/subgid files must exist for user namespace remapping to work:
# Create the files if they don't exist
sudo touch /etc/subuid /etc/subgidThese files define which subordinate UID/GID ranges can be used by each user for namespace remapping.
When using "userns-remap": "default", Docker expects a user called dockremap:
# Create the dockremap user (system user, no home directory, no login)
sudo useradd -r -s /bin/false dockremap
# Add subordinate UID/GID mappings
# This maps container UID 0 to host UID 500000, with 65536 available IDs
echo "dockremap:500000:65536" | sudo tee -a /etc/subuid
echo "dockremap:500000:65536" | sudo tee -a /etc/subgidChoose a starting UID (like 500000) that doesn't overlap with existing users on your system. The range 65536 provides enough IDs for typical container workloads.
Edit or create /etc/docker/daemon.json:
sudo nano /etc/docker/daemon.jsonAdd the userns-remap configuration:
{
"userns-remap": "default"
}Or specify a custom user:
{
"userns-remap": "dockremap"
}Save the file and restart Docker:
sudo systemctl restart dockerAfter restarting Docker, verify the configuration:
docker info | grep -i usernsYou should see output like:
Security Options: usernsCheck the Docker root directory - it should include the UID mapping:
docker info | grep "Docker Root Dir"With userns-remap enabled, this will show something like /var/lib/docker/500000.500000 instead of just /var/lib/docker.
Test with a container:
docker run --rm alpine idInside the container, this shows uid=0(root), but processes are actually running as an unprivileged user on the host.
If you don't need user namespace remapping and just want Docker to work, remove the configuration:
# Edit daemon.json
sudo nano /etc/docker/daemon.jsonRemove the "userns-remap" line or the entire file if it only contained that setting.
# Restart Docker
sudo systemctl restart dockerThis reverts to standard Docker behavior where container root equals host root (inside the container's namespace).
Security Trade-offs:
User namespace remapping significantly improves container isolation. With userns-remap enabled, a container breakout that achieves root access only gains privileges as an unprivileged user on the host. However, this feature has compatibility implications:
- --privileged containers won't work without --userns=host
- --pid=host and --network=host are incompatible
- Some volume drivers may not support remapped UIDs
- Existing images and containers become invisible (stored in a different directory)
Kernel Configuration Requirements:
The kernel must be compiled with CONFIG_USER_NS=y. Most modern distributions include this, but enterprise distributions like RHEL 7 disable it by default for stability reasons. Check with:
zcat /proc/config.gz 2>/dev/null | grep USER_NS || cat /boot/config-$(uname -r) | grep USER_NSSELinux Interactions:
On SELinux-enabled systems (RHEL, CentOS, Fedora), you may encounter additional restrictions. If user namespaces work but containers fail:
# Check for SELinux denials
sudo ausearch -m avc -ts recent | grep userns
# Temporarily set permissive mode for testing
sudo setenforce 0Volume Permission Issues:
With userns-remap, files created in volumes will be owned by the remapped UID (e.g., 500000) on the host. To share data between host and container:
# Use named volumes (Docker manages permissions)
docker volume create mydata
docker run -v mydata:/data alpine touch /data/file
# Or adjust host directory ownership
sudo chown -R 500000:500000 /path/to/host/dirPer-Container Override:
To run a specific container without user namespace remapping (while keeping it enabled globally):
docker run --userns=host --rm alpine idThis is useful for containers that require true root access, like system monitoring tools.
Rootless Docker Alternative:
For even stronger isolation, consider rootless Docker which runs the entire daemon as a non-root user:
dockerd-rootless-setuptool.sh installRootless Docker provides similar security benefits without requiring kernel-level user namespace configuration.
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