🦭 Podman Error: 'unable to start container: cannot re-exec process' in Rootless Mode

Exact Error Message

$ podman run --rm -it docker.io/library/alpine:3.19 sh
ERRO[0000] cannot find UID/GID for user deploy: no subuid ranges found for user "deploy" in /etc/subuid - check rootless mode in man pages.
WARN[0000] Using rootless single mapping into the namespace. This might break some images.
Error: unable to start container 4c1f...: cannot re-exec process

A closely related variant appears when the range exists but is too small:

Error: writing file `/proc/self/gid_map`: Invalid argument: there might not be enough IDs available in the namespace (requested 0:100 for /etc/group): potentially insufficient UIDs or GIDs available in user namespace

What It Means

Rootless Podman runs containers inside a user namespace. Your unprivileged user ID is mapped to UID 0 inside the container, and a block of additional subordinate IDs is mapped to the remaining container UIDs so that files owned by nobody, www-data, or any other in-image user have somewhere to land. That block comes from /etc/subuid and /etc/subgid. Podman does not create the namespace itself — it re-executes itself through the setuid-capable helpers newuidmap and newgidmap, which read those files and write the mappings into /proc/self/uid_map and /proc/self/gid_map. “cannot re-exec process” is Podman reporting that this hand-off failed.

There are only a handful of ways it can fail, and they are all environmental. Either the user has no entry in /etc/subuid//etc/subgid at all (very common for LDAP or SSSD users, whose accounts never pass through useradd), or the range is present but smaller than the image needs, or newuidmap/newgidmap are missing or have lost the file capabilities that let them write mappings for more than a single ID, or the kernel is refusing new user namespaces because user.max_user_namespaces is zero. The error text is generic because Podman only sees that the helper exited non-zero; the specific cause is always visible in the files and capabilities described below.

Common Causes

• The user has no line in /etc/subuid and /etc/subgid — typical for accounts created by LDAP/SSSD, cloud-init, or a manual adduser --system.
• The subordinate range is too small (fewer than 65536 IDs), so images referencing high UIDs cannot be mapped.
• The uidmap / shadow-utils package providing newuidmap and newgidmap is not installed, especially in slim container base images running nested Podman.
• newuidmap/newgidmap lost their cap_setuid/cap_setgid file capabilities — often after a cp across filesystems, a container image rebuild, or a security-hardening sweep.
• user.max_user_namespaces is set to 0 by a hardening profile, forbidding unprivileged user namespaces entirely.
• Subuid ranges were changed but Podman’s existing containers and storage still reference the old mapping, requiring podman system migrate.

Diagnostic Commands

First confirm the user actually has subordinate ranges:

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

An empty result is the answer. If lines exist, check the size — the third field is the count and should be at least 65536:

awk -F: -v u="$(id -un)" '$1==u {print FILENAME": start="$2" count="$3}' /etc/subuid /etc/subgid

Verify the mapping helpers exist and still carry their capabilities. Missing capabilities here are a silent, extremely common cause:

which newuidmap newgidmap
getcap /usr/bin/newuidmap /usr/bin/newgidmap

You expect something like cap_setuid=ep and cap_setgid=ep. Next, confirm the kernel permits unprivileged user namespaces:

sysctl user.max_user_namespaces
cat /proc/sys/user/max_user_namespaces

Finally, ask Podman to show the mapping it can construct right now. This is the single most useful check because it exercises the same code path as podman run:

podman unshare cat /proc/self/uid_map
podman unshare cat /proc/self/gid_map
podman info --format '{{.Host.IDMappings}}'

A healthy result shows two rows: your UID mapped to 0, and a large block starting at 1.

Step-by-Step Resolution

1. If the user has no ranges, add them with usermod, which picks a non-overlapping block and writes both files correctly:

sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 deploy
grep "^deploy:" /etc/subuid /etc/subgid

2. For LDAP/SSSD users who will never be in local passwd, append the entries directly, making sure ranges do not overlap other users:

echo "deploy:200000:65536" | sudo tee -a /etc/subuid
echo "deploy:200000:65536" | sudo tee -a /etc/subgid

3. Install the helpers if which newuidmap came back empty:

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

4. Restore the file capabilities if getcap printed nothing. Without these, the helpers can only map a single ID, which produces the “single mapping” warning above:

sudo setcap cap_setuid+ep /usr/bin/newuidmap
sudo setcap cap_setgid+ep /usr/bin/newgidmap
getcap /usr/bin/newuidmap /usr/bin/newgidmap

5. Re-enable unprivileged user namespaces if the sysctl is zero, and persist it:

sudo sysctl -w user.max_user_namespaces=28633
echo 'user.max_user_namespaces=28633' | sudo tee /etc/sysctl.d/99-userns.conf

6. After any subuid/subgid change, migrate existing containers and storage so they adopt the new mapping, then verify:

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

If containers still fail to start after the mapping is correct, the failure has moved further down the stack — check the runtime and cgroup layer via crun sd-bus transport endpoint and cgroup v1 not supported.

Prevention

• Provision subuid/subgid ranges as part of user creation in your configuration management, not ad hoc after the first failure.
• Allocate a full 65536-ID block per user; smaller ranges break any image using high UIDs.
• Add a getcap /usr/bin/newuidmap assertion to host validation so a hardening sweep that strips capabilities is caught immediately.
• Handle LDAP/SSSD users explicitly — they never get automatic /etc/subuid entries.
• Pin user.max_user_namespaces in /etc/sysctl.d/ so a hardening profile cannot zero it silently.
• Always run podman system migrate in the same change window as any subuid range edit.

Related Errors

• there might not be enough IDs available in the namespace — the range exists but is too small; widen it to 65536 and re-migrate.
• Using rootless single mapping into the namespace — a warning that newuidmap lacks capabilities, so only one ID was mapped.
• potentially insufficient UIDs or GIDs available in user namespace — same root cause, surfaced while chowning image layers.
• cannot clone: Operation not permitted — user.max_user_namespaces is zero or a seccomp/AppArmor profile is blocking namespace creation.

Frequently Asked Questions

Why does this work as root but not as my user? Root does not need a user namespace, so it never touches /etc/subuid or newuidmap. Rootless Podman depends on both, which is why the failure is exclusive to the unprivileged path.

How many subordinate IDs do I actually need? 65536 is the practical standard. Many images reference UIDs like 65534 (nobody), and a shorter range makes those unmappable, producing the “not enough IDs” companion message even though a mapping technically exists.

Do I have to run podman system migrate after changing ranges? Yes. Existing containers and the image store record the old mapping, and they will keep failing until migrate rewrites them. It is safe to run when nothing is broken.

My user is from LDAP and usermod fails — what now? Append the ranges to /etc/subuid and /etc/subgid by hand, choosing a start value that does not overlap any existing block. Podman reads those files directly and does not require the user to exist in local passwd. For more container fixes, see the Podman guides.