🐳 Docker Error Guide: 'newuidmap: write to uid_map failed' Rootless Setup

Exact Error Message

[rootlesskit:parent] error: failed to setup UID/GID map:
newuidmap 12345 0 1000 1 1 100000 65536 failed:
newuidmap: write to uid_map failed: Operation not permitted
exit status 1
[rootlesskit:child ] error: parent failed to start

You may also see the GID counterpart, newgidmap: write to gid_map failed: Operation not permitted, or the earlier variant newuidmap: uid range [1-65536) -> [100000-165536) not allowed, which points at the same subuid/subgid configuration problem.

What It Means

Rootless Docker runs the daemon inside a user namespace where your single host UID is mapped onto a range of thousands of unprivileged sub-UIDs. The newuidmap and newgidmap helpers perform that mapping by writing to /proc/<pid>/uid_map and gid_map. Those writes require the helpers to be setuid root, and the ranges they may assign must be declared in /etc/subuid and /etc/subgid.

Operation not permitted means one of two guarantees is broken: either the helper binary has lost its setuid bit (so it runs unprivileged and the kernel rejects the map write), or your user has no valid sub-UID/sub-GID allocation to map into. RootlessKit cannot build the namespace, so the daemon never starts.

Common Causes

• Your user has no entry in /etc/subuid and/or /etc/subgid.
• The sub-ID range is too small (rootless Docker needs at least 65,536 IDs).
• newuidmap/newgidmap lost their setuid bit, often after a chmod -R, a restore, or a hardening script.
• The uidmap package (which ships those helpers) is not installed.
• A read-only or nosuid-mounted filesystem prevents the setuid bit from taking effect.
• Duplicate or overlapping ranges in /etc/subuid for different users.

Diagnostic Commands

Check whether your user has sub-ID allocations:

grep "^$(whoami):" /etc/subuid /etc/subgid

Verify the helper binaries are present and setuid root:

ls -l "$(command -v newuidmap)" "$(command -v newgidmap)"

Look for the -rwsr-x / s bit; if you see -rwxr-xr-x, the setuid bit is gone.

Confirm the uidmap package is installed:

dpkg -l | grep uidmap        # Debian/Ubuntu
rpm -q shadow-utils          # RHEL/Fedora

Reproduce the failure and capture the full RootlessKit trace:

systemctl --user restart docker
journalctl --user -u docker --no-pager -n 40

Step-by-Step Resolution

1. Install the helpers if they are missing. On Debian/Ubuntu:

sudo apt-get update && sudo apt-get install -y uidmap

2. Add a sub-UID and sub-GID range for your user. Use a non-overlapping block of at least 65,536 IDs:

sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 "$(whoami)"

If usermod is unavailable, append directly:

echo "$(whoami):100000:65536" | sudo tee -a /etc/subuid
echo "$(whoami):100000:65536" | sudo tee -a /etc/subgid

3. Restore the setuid bit on both helpers if ls -l showed it missing:

sudo chmod u+s "$(command -v newuidmap)" "$(command -v newgidmap)"

4. Confirm the helpers are not on a nosuid mount, which would silently defeat the setuid bit:

findmnt -no OPTIONS -T "$(command -v newuidmap)"

If nosuid appears, the binaries must live on a filesystem mounted without it.

5. Restart the rootless daemon so RootlessKit rebuilds the namespace with the new ranges:

systemctl --user restart docker

6. Verify the daemon is healthy and running rootless:

docker info --format '{{.SecurityOptions}}'
docker run --rm hello-world

The SecurityOptions line should include name=rootless, and hello-world should print its greeting.

Prevention

• Provision /etc/subuid and /etc/subgid as part of user creation so every rootless user starts with a valid 65,536-ID block.
• Avoid recursive chmod on /usr/bin; hardening scripts that strip setuid bits are the most common regression here.
• Pin the uidmap/shadow-utils package in your base image or golden AMI so the helpers are always present.
• Keep sub-ID ranges non-overlapping across users to prevent cross-namespace collisions.
• Run dockerd-rootless-setuptool.sh check after provisioning to validate the whole rootless prerequisite chain in one shot.

Related Errors

• could not get XDG_RUNTIME_DIR — a rootless environment problem where the user session bus is missing, not a UID-map issue.
• [rootlesskit:parent] error: failed to start the child: fork/exec ... slirp4netns — the networking helper is missing rather than the ID-map helper.
• docker: 'rootless' not found — the setup tool never ran; distinct from a map-write failure.
• newuidmap: uid range ... not allowed — the same root cause (missing/short subuid) surfacing before the write attempt.

Frequently Asked Questions

How many sub-UIDs does rootless Docker need? At least 65,536 contiguous IDs per user. A short range such as :100000:1000 will map the root user inside the container but fail as soon as an image references a higher UID.

Why did this break after a security-hardening run? Hardening scripts frequently strip setuid bits across /usr/bin. newuidmap/newgidmap must stay setuid root; re-apply with chmod u+s. You can template a validation prompt from the DevOps AI prompt library at /prompts/?stack=docker to audit these bits in CI.

Do I need to edit /etc/subuid by hand? Prefer usermod --add-subuids/--add-subgids, which picks a non-overlapping range and updates both the login and namespace databases consistently. Manual edits work but are easy to overlap.

Can I run rootless Docker without the newuidmap helpers? No. Without the setuid newuidmap/newgidmap (from the uidmap package), the kernel refuses the multi-ID map write and RootlessKit cannot create the namespace.

What is the fastest way to confirm the whole setup is valid? Run dockerd-rootless-setuptool.sh check, which validates subuid/subgid, the helpers, and kernel prerequisites in one pass. For more rootless and daemon fixes, see the Docker guides.