🦭 Podman Error: 'cannot set up namespace using newuidmap: exit status 1' in Rootless Mode

Exact Error Message

$ podman run --rm docker.io/library/alpine:latest echo hi
Error: cannot set up namespace using "/usr/bin/newuidmap": exit status 1

A closely related variant names the group-mapping helper instead:

$ podman info
ERRO[0000] cannot set up namespace using "/usr/bin/newgidmap": should have setuid or have filecaps setuid
Error: cannot re-exec process

What It Means

Rootless Podman runs every container inside a user namespace. Inside that namespace your unprivileged user appears as UID 0, and a range of additional subordinate UIDs is mapped so the container can also have users like nobody or an application UID such as 1001. Setting up that mapping is a privileged operation, so Podman shells out to newuidmap and newgidmap — small setuid helpers from the shadow-utils (Fedora/RHEL) or uidmap (Debian/Ubuntu) package — which write to /proc/<pid>/uid_map and /proc/<pid>/gid_map on Podman’s behalf.

Those helpers only agree to write a mapping that is authorized by /etc/subuid and /etc/subgid. Each line in those files grants one user a contiguous block of subordinate IDs. If your user has no entry, has an entry that overlaps another user’s block, or the helper binary has lost its setuid bit or file capabilities, newuidmap exits non-zero and Podman reports it verbatim. The exit status 1 is deliberately terse — the real detail lives in the two /etc/sub* files and in the permission bits on the binaries.

Common Causes

• The user has no line in /etc/subuid and/or /etc/subgid at all.
• The user was created by LDAP, SSSD, FreeIPA, or Active Directory, which do not populate the local /etc/sub* files.
• The uidmap (Debian/Ubuntu) or shadow-utils (RHEL/Fedora) package is not installed, so the helper binaries are missing.
• /usr/bin/newuidmap or /usr/bin/newgidmap lost its setuid bit or cap_setuid/cap_setgid file capability, often after a container-image rebuild or an rsync-based deploy.
• Two users were given overlapping subordinate ranges, which newuidmap refuses.
• The subuid range was edited but podman system migrate was never run, so existing containers still reference the old mapping.

Diagnostic Commands

Check whether your user has subordinate ranges at all:

grep "^$(id -un):" /etc/subuid /etc/subgid

Inspect the helper binaries for the setuid bit or file capabilities:

ls -l /usr/bin/newuidmap /usr/bin/newgidmap
getcap /usr/bin/newuidmap /usr/bin/newgidmap

Confirm the package that owns them is installed:

# Debian / Ubuntu
dpkg -S /usr/bin/newuidmap || apt-cache policy uidmap
# RHEL / Fedora
rpm -qf /usr/bin/newuidmap

Ask Podman what it believes the current mapping is:

podman info --format '{{ .Host.IDMappings }}'

Look for overlapping or duplicated ranges across all users:

sort -t: -k2 -n /etc/subuid

Step-by-Step Resolution

1. Install the package that provides the helpers if they are missing:

# Debian / Ubuntu
sudo apt-get install -y uidmap
# RHEL / Fedora / CentOS Stream
sudo dnf install -y shadow-utils

2. Grant your user a subordinate range. The tooling-friendly way is usermod, which picks a non-overlapping block for you:

sudo usermod --add-subuids 200000-265535 --add-subgids 200000-265535 deployuser

3. If you prefer to write the files directly, add one line per user to each file. The format is name:start:count, and 65536 is the conventional size:

echo 'deployuser:200000:65536' | sudo tee -a /etc/subuid
echo 'deployuser:200000:65536' | sudo tee -a /etc/subgid

4. Restore the setuid bit if the helpers lost it. On distributions that use file capabilities instead, set those:

sudo chmod u+s /usr/bin/newuidmap /usr/bin/newgidmap
# or, on capability-based installs:
sudo setcap cap_setuid+ep /usr/bin/newuidmap
sudo setcap cap_setgid+ep /usr/bin/newgidmap

5. Whenever the range changes, tell Podman to rebuild its storage with the new mapping. This is required — existing containers were created against the old IDs and will not simply pick up the new ones:

podman system migrate

If the user has no containers worth keeping, a full reset is faster and guarantees no stale mappings remain:

podman system reset

6. Verify the namespace now sets up cleanly, and inspect the resulting map from inside it:

podman unshare cat /proc/self/uid_map
podman run --rm docker.io/library/alpine:latest id

For directory-server accounts, the /etc/sub* files are the only place these ranges can live — SSSD does not serve them. Add the entries on every host the user logs into, or generate them from the directory UID with a small provisioning script so they stay consistent across the fleet.

Prevention

• Provision /etc/subuid and /etc/subgid entries as part of host bootstrap, not as a manual fix after the first failure.
• For LDAP/SSSD/IPA users, run a configuration-management task that derives a deterministic, non-overlapping range from the directory UID.
• Allocate 65536 IDs per user and space blocks at fixed intervals so ranges can never overlap.
• Always run podman system migrate immediately after editing a range, and document that step in your runbook.
• Do not strip setuid bits wholesale in image or host hardening jobs; explicitly allowlist newuidmap and newgidmap.
• Add a health check that runs podman unshare true on each host so a broken mapping is detected before a deploy needs it.

Related Errors

• potentially insufficient UIDs or GIDs available in user namespace — the mapping exists but is too small for the image’s file ownership; see Podman error: potentially insufficient UIDs or GIDs available in user namespace.
• Error: cannot clone: Operation not permitted — the kernel is blocking unprivileged user-namespace creation entirely, a sysctl issue rather than a subuid one.
• Error: max user namespaces exceeded — the user.max_user_namespaces limit has been hit; see Podman error: max user namespaces exceeded.
• newuidmap: write to uid_map failed: Operation not permitted — the requested mapping exceeds what /etc/subuid authorizes for that user.

Frequently Asked Questions

Why does sudo podman run work when rootless fails? Running as root does not need a user namespace at all, so newuidmap is never invoked. That it works under sudo confirms the problem is in the rootless ID-mapping setup, not in the image, storage, or network.

Do I need to log out after editing /etc/subuid? Not strictly, but you must run podman system migrate so existing containers and the storage layer are re-created against the new range. Starting a fresh login session as well avoids stale environment state in long-lived shells.

How large should the range be? 65536 is the conventional size and is what usermod --add-subuids allocates by default. It covers the vast majority of images. Only widen it if a specific image ships files owned by very high UIDs.

Can two users share the same subordinate range? No. Overlapping ranges let one user’s containers touch another user’s files on shared storage, and newuidmap rejects the configuration outright. Give every user a distinct block. For more rootless container fixes, see the Podman guides.