Linux Podman Rootless UID Mapping Error — What It Means & How to Fix It

Fix Podman rootless container UID mapping errors when user namespace configuration prevents container processes from running correctly. This guide covers everything you need to know about this topic, including common causes, step-by-step solutions, and answers to frequently asked questions.

Here are the key things to understand: Rootless Podman runs containers without root privileges using user namespaces for UID/GID mapping. UID mapping errors occur when /etc/subuid or /etc/subgid do not allocate enough subordinate IDs. Container processes running as different UIDs need mapped ranges in the host's user namespace. This is a common issue on newly set up systems or when user accounts are created manually. Understanding these fundamentals will help you diagnose and resolve this issue more effectively.

The most common reasons this occurs include: User does not have entries in /etc/subuid and /etc/subgid. Allocated subordinate UID range is too small for the container's requirements. User namespace kernel feature is not enabled. Incompatible kernel configuration (user.max_user_namespaces = 0). Identifying the root cause is the first step toward finding the right solution.

To resolve this, follow these recommended steps: Check subordinate IDs: grep $USER /etc/subuid /etc/subgid (should have entries like user:100000:65536). Add entries if missing: sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 $USER. Verify user namespaces: cat /proc/sys/user/max_user_namespaces (should be > 0). Reset Podman storage after changes: podman system migrate to apply the new ID mappings. If these steps do not resolve the issue, consider consulting additional resources or a qualified professional.

This article is part of our Linux Error Codes collection on Error Codes Wiki. We provide comprehensive, up-to-date information to help you find solutions quickly.