🐳 Docker Error Guide: 'userns-remap' subuid/subgid and Bind-Mount Permission Failure

Exact Error Message

Error response from daemon: failed to create endpoint on network bridge:
open /proc/sys/net/ipv6/conf/.../accept_dad: permission denied

# or, at daemon startup:
failed to start daemon: Error initializing user namespaces:
Can't create ID mappings: no subuid ranges found for user "dockremap" (or gid)

You may also see permission denied when a container writes to a bind-mounted host directory, mkdir: cannot create directory: Permission denied, or chown ... operation not permitted after enabling userns-remap. These all stem from user-namespace remapping changing which host UID/GID the container actually runs as.

What It Means

With userns-remap enabled, Docker runs container processes under a remapped, unprivileged range of host UIDs/GIDs. Root inside the container (UID 0) maps to a high, non-privileged host UID (for example 165536). This is a strong security hardening: a container “root” cannot touch host-root files.

The trade-off is that host resources must be owned by the remapped range. If the /etc/subuid and /etc/subgid ranges for the remap user are missing, the daemon cannot even start. If a bind-mounted host directory is owned by real root (0:0), the remapped container process has no rights to it and fails with permission denied.

Common Causes

• No subuid/subgid range exists for the remap user (default dockremap), so the daemon refuses to start.
• A bind-mounted host path is owned by host UID 0, but the container now runs as a remapped high UID.
• Named volumes or bind mounts created before enabling remap keep their old ownership.
• /etc/subuid and /etc/subgid were edited but the daemon was not restarted.
• The remap range overlaps another user’s range, or the dockremap user was never created.
• Filesystems mounted nosuid/with restrictive options block the remapped IDs.

Diagnostic Commands

Confirm remapping is active and see the current user:

docker info --format "Security Options: {{.SecurityOptions}}"
grep userns-remap /etc/docker/daemon.json

Check the subuid/subgid ranges for the remap user:

grep dockremap /etc/subuid /etc/subgid
id dockremap

Find the remapped base UID Docker is using:

ls -ln /var/lib/docker/  # look for the 165536.165536 style directory

Inspect ownership of a failing bind-mount path:

ls -ln /srv/appdata

Step-by-Step Resolution

1. If the daemon will not start, create the remap user and its ID ranges, then restart:

sudo useradd -r -s /usr/sbin/nologin dockremap 2>/dev/null || true
echo "dockremap:165536:65536" | sudo tee -a /etc/subuid
echo "dockremap:165536:65536" | sudo tee -a /etc/subgid
sudo systemctl restart docker

2. Confirm userns-remap is set in the daemon config (use the sentinel default to auto-manage dockremap):

{
  "userns-remap": "default"
}

3. Identify the remapped base UID/GID. With a 165536:65536 range, container root maps to host UID 165536.

4. Chown bind-mount host directories to the remapped range so the container can write. If the container process runs as container-UID 0, use the base; for container-UID 1000, add 1000:

# container root -> host 165536
sudo chown -R 165536:165536 /srv/appdata

# container uid 1000 -> host 166536
sudo chown -R 166536:166536 /srv/appdata

5. Run the container against the corrected path and confirm writes succeed:

docker run --rm -v /srv/appdata:/data alpine sh -c "touch /data/ok && echo wrote"

6. For data that must stay host-root owned, exclude that specific container from remapping instead of chowning:

docker run --userns=host --rm -v /srv/rootdata:/data alpine ls -ln /data

7. Verify the fix end to end:

wrote

Prevention

• Add dockremap entries to /etc/subuid and /etc/subgid as part of host provisioning, before enabling remap.
• Standardize on a single remap base (for example 165536) across the fleet so ownership math is predictable.
• Chown application data directories to the remapped range in your infrastructure-as-code, not by hand after the fact.
• Reserve --userns=host for the few containers that genuinely need host-root-owned mounts, and document why.
• Always systemctl restart docker after editing daemon.json or the subid files; changes are not live until restart.

Related Errors

• no subuid ranges found for user "dockremap" — the daemon-startup form of a missing ID range.
• operation not permitted on chown inside a container — the remapped root lacks host capabilities.
• failed to register layer: ApplyLayer ... permission denied — image-layer extraction hitting the remap boundary.
• mkdir /var/lib/docker/165536.165536: file exists — a stale remap data root from a previous range.

Frequently Asked Questions

Why won’t the Docker daemon start after I enable userns-remap? Almost always because /etc/subuid and /etc/subgid have no range for the remap user. Add a dockremap:165536:65536 line to both and restart.

How do I find the host UID my container root maps to? Look at the base of the remap range (commonly 165536) or the 165536.165536 directory under /var/lib/docker. Container UID N maps to base + N.

Why do bind mounts fail with permission denied after enabling remap? The container no longer runs as host root, so host-root-owned directories are unwritable. Chown the mount to the remapped range or use --userns=host for that container.

Can I exclude one container from remapping? Yes. Run it with --userns=host, which opts that container out and lets it use host UID/GID directly for sensitive mounts. Generate subuid/chown fixes fast with the DevOps AI prompt library.

Do I need to restart Docker after editing subuid/subgid? Yes. The daemon reads those ranges only at startup, so run systemctl restart docker after any change. See more Docker guides.