Podman Troubleshooting Guide: Common Errors and Fixes

You have a Podman error string or a container that does not behave. This page is a routing index: match the literal symptom, run one or two first checks, then open the dedicated guide that owns the fix. It does not replace those articles with shortened copies.

Capture environment information first

Many Podman failures depend on baseline context before you chase a symptom:

• Version — behavior and flags differ across Podman releases
• Rootful versus rootless — storage paths, namespaces, and port binding
• Filesystem — overlay layout, mounts, and quota on graphRoot
• Networking — Netavark backend and the active container/rootless network mode

Record those facts next.

Check the Podman version:

podman version

Sample output on the lab host:

Client:        Podman Engine
Version:       5.8.2
API Version:   5.8.2
Go Version:    go1.26.5 (Red Hat 1.26.5-1.el10_2)
Built:         Fri Jul 10 05:30:00 2026
OS/Arch:       linux/amd64

Collect host runtime details:

podman info

On the lab host the summary includes cgroupVersion: v2, networkBackend: netavark, distribution: rhel 10.2, kernel 6.12.0-211.47.1.el10_2.x86_64, and graph driver overlay under /var/lib/containers/storage. Rootless failures often differ in graphRoot, runRoot, and idMappings — compare your output to a known-good rootful host when users report “works as root, fails as my user.”

Quick Podman diagnostic commands

Use these commands to narrow a symptom before you open a fix guide. Each answers a different question:

• container state
• image presence
• runtime configuration
• workload output
• recent events
• storage use
• store integrity

Replace CONTAINER with the name or ID from podman ps -a.

Exited (0), Exited (137), and Exited (139)

podman ps -a may show:

Exited (0)
Exited (137)
Exited (139)

Exit 0 usually means the main process finished — not necessarily a failure. 137 is SIGKILL (OOM, stop timeout, or manual kill). 139 is SIGSEGV inside the workload.

First check:

podman inspect --format 'ExitCode={{.State.ExitCode}} OOMKilled={{.State.OOMKilled}}' CONTAINER

Full exit-code diagnosis lives in Fix container exits immediately.

executable file not found in $PATH

Error: crun: executable file `python` not found in $PATH: No such file or directory

Podman started the container but the command is missing inside the image. Container exit status is often 127.

First check:

podman inspect --format '{{json .Config.Entrypoint}} {{json .Config.Cmd}}' CONTAINER

See Fix container exits immediately for exit 127 and ENTRYPOINT mismatches.

permission denied when executing a container command

Error: ... permission denied ...

Common causes include:

• non-executable file or script
• noexec mount on the command path
• SELinux denial unrelated to volume labels
• wrong interpreter or missing shebang

Not every permission denied on a command is a volume label problem.

First check:

podman logs CONTAINER

If the denial happens on a mounted path, continue to the volume section below. Otherwise use the exits guide for command and mount context.

Permission denied on a volume path

Inside the container:

touch: cannot touch '/data/file': Permission denied

Likely SELinux label mismatch, rootless UID/GID mapping, or a filesystem without xattr support.

First check:

ls -lZ /host/path/to/mount

Full :z, :Z, :U, and keep-id workflows are in Fix volume permission denied.

lsetxattr ... operation not permitted

Error: lsetxattr(...): operation not permitted

Common when rootless Podman tries to relabel a host path on NFS, CIFS, or another remote filesystem that cannot store SELinux xattrs.

First check:

findmnt -no FSTYPE,SOURCE /host/path

Route to Fix volume permission denied — do not loop :z on unsupported exports.

there might not be enough IDs available in the namespace

... there might not be enough IDs available in the namespace ...

Usually subordinate UID/GID ranges are missing, exhausted, or misconfigured for rootless Podman.

First check:

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

Setup and range repair: Rootless Podman setup.

not enough unused IDs in user namespace

Error: creating container storage: not enough unused IDs in user namespace

Often keep-id, nomap, or auto user namespace modes consuming the subordinate range.

First check:

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

See Podman user namespaces.

Cannot find mappings for user "containers"

Error: ... Cannot find mappings for user "containers": no subuid ranges found for user "containers" in /etc/subuid

The storage driver expected a containers user mapping that does not exist on the host.

First check:

grep containers /etc/subuid /etc/subgid

Fix ranges and namespace mode in Podman user namespaces.

XDG_RUNTIME_DIR ... is not owned by the current user

ERRO[...] XDG_RUNTIME_DIR directory "/run/user/..." is not owned by the current user

Typical after su user without a login session — the shell inherited another user's runtime directory.

First check:

stat -c '%u %U %n' "$XDG_RUNTIME_DIR"

Session and runtime fixes: Rootless Podman setup.

Rootless Quadlet or systemd container stops at logout

Symptom pattern:

Before logout: Up ...
After login:   Exited (...)

Rootless workloads managed by the user systemd instance may stop or fail to remain available after the user's login session ends when lingering is not enabled.

First check:

loginctl show-user "$(whoami)" -p Linger

See Fix container stops after logout.

short-name resolution enforced but cannot prompt without a TTY

Error: short-name resolution enforced but cannot prompt without a TTY

Enforcing mode blocked an ambiguous short name in CI, Quadlet, or a non-interactive shell.

First check:

podman pull docker.io/library/IMAGE:TAG

Use a fully qualified name or configure aliases: Fix short-name resolution errors.

x509: certificate signed by unknown authority

x509: certificate signed by unknown authority

The registry TLS certificate is not trusted by the host or the pull uses the wrong scheme.

First check:

curl -vI https://REGISTRY_HOST/v2/

Registry trust and corporate CA fixes: Fix x509 certificate unknown authority. For plain HTTP registries, see Run a private container registry.

http: server gave HTTP response to HTTPS client

http: server gave HTTP response to HTTPS client

You pointed Podman at https:// but the registry speaks plain HTTP.

First check:

grep -E '^location|^prefix' /etc/containers/registries.conf

Same TLS article or Run a private container registry depending on your registry layout.

toomanyrequests

toomanyrequests: You have reached your unauthenticated pull rate limit. https://www.docker.com/increase-rate-limit

Docker Hub rejected the manifest request — authentication, wait, mirror, or alternate registry required.

First check:

podman login docker.io

Full rate-limit workflow: Fix Docker Hub rate limit.

no space left on device

... no space left on device

Blocks, inodes, or storage quota exhausted — not always the root filesystem.

First check:

df -h && df -i

See Fix no space left on device.

Overlay and layer storage errors

Examples:

... layer not known ...
... lower layer ...
... overlay ... no such file or directory ...

Often corrupted local storage or a partial image extract.

First check:

podman system check

Repair paths: Repair storage corruption and reset.

Container cannot reach the Internet

Name resolution and routing failures often look like this:

curl: (6) Could not resolve host: example.com
connect: Network is unreachable

First check inside the container:

podman exec CONTAINER ip route

External connectivity: Fix container cannot access Internet. Container-name DNS: Podman DNS and name resolution.

Connection refused on a published port

curl: (7) Failed to connect to 127.0.0.1 port 8080: Connection refused

The publish path or application listener is wrong — not always firewall.

First check:

podman port CONTAINER

See Fix port mapping not working.

Connection reset by peer

curl: (56) Recv failure: Connection reset by peer

TCP reached a listener but the service closed without a valid response.

First check inside the container:

podman exec CONTAINER ss -lntp

Same port-mapping guide: Fix port mapping not working.

cannot set port bindings on a pod member

Podman 5.8.x and older releases phrase the same pod networking mistake differently:

Error: invalid config provided: published or exposed ports must be defined when the pod is created: network cannot be configured when it is shared with a pod
Error: cannot set port bindings on an existing container network namespace

Publish on podman pod create, not on podman run --pod.

First check:

podman pod inspect POD --format '{{json .InfraConfig.PortBindings}}'

Podman pod networking and Fix port mapping not working.

Rootless host port below 1024

Pasta and rootlessport failures on ports 80 or 443 often read:

Error: pasta failed with exit code 1:
Failed to bind port 80 (Permission denied) for option '-t 80-80:8080-8080'
Listen failed for HOST TCP port */80: Permission denied
Couldn't listen on requested TCP ports

Unprivileged users cannot bind privileged host ports without sysctl, redirect, or proxy workarounds.

First check:

podman run --rm -p 8080:80 IMAGE

See Rootless Podman privileged ports.

exec format error

{"msg":"exec container process `/run.sh`: Exec format error","level":"error"}

Wrong CPU architecture or a script without a shebang.

First check:

podman image inspect --format '{{.Architecture}}' IMAGE

Fix exec format error.

Quadlet Unit ... not found

Failed to start web.service: Unit web.service not found.

The generator did not install the unit, or systemd has not reloaded.

First check:

/usr/lib/systemd/system-generators/podman-system-generator --dryrun

For rootless units:

/usr/lib/systemd/system-generators/podman-system-generator --user --dryrun

Some distributions also install /usr/libexec/podman/quadlet; use the generator path shown by your package when it differs. Podman also recommends systemd-analyze ... --generators=true verify when you need to confirm generator errors.

Quadlet troubleshooting.

Cgroup controller not available

crun: the requested cgroup controller `cpu` is not available

Resource limits need cgroup v2 controllers delegated to the user session.

First check:

podman info --format 'CgroupControllers={{.Host.CgroupControllers}}'

Set CPU and memory limits.

Registry unauthorized

unauthorized: authentication required

Missing or expired registry credentials.

First check:

podman login REGISTRY_HOST

Log in to a container registry.

Cannot connect to Podman socket

Error: unable to connect to Podman socket: ...

Remote API or Docker-compatible socket misconfiguration.

First check:

echo "$DOCKER_HOST"

SSH remote workflow: Manage remote Podman hosts. Local Docker API socket: Podman socket and Docker API.

Container health is unhealthy

unhealthy

The healthcheck command failed repeatedly.

First check:

podman inspect --format '{{json .State.Health}}' CONTAINER

Configure container health checks.

Symptom to article routing table

Related setup guides outside the error library

Some failures route to setup or concept articles that are not numbered troubleshooting lessons:

Collect information before reporting a Podman bug

Upstream bug reports need reproducible facts, not screenshots alone.

Capture versions:

podman version

Add debug host state:

podman info --debug

Re-run the failing command with debug logging:

podman --log-level=debug COMMAND

Include the exact command, full stderr, rootless versus rootful context, OS and kernel from podman info, and package NEVRAs. Remove registry passwords, tokens, and private image URLs before you paste logs into a public tracker.

References

• podman-troubleshooting(7) — Podman documentation
• podman-info(1) — Podman documentation
• podman-inspect(1) — Podman documentation
• Red Hat — Building, running, and managing containers

Summary

Podman troubleshooting starts with context: podman version, podman info, and whether the failure is rootful or rootless. Match the literal error or podman ps -a status to a category — exit codes, permissions, registry TLS, storage, network, ports, architecture, Quadlet, or cgroup limits — then run the one or two first checks listed for that row.

This index quotes symptoms and routes you to dedicated guides. It does not replace them. Volume SELinux and UID mapping live in the volume permissions article; subuid and XDG_RUNTIME_DIR issues live in rootless setup; external versus name DNS split across the no-Internet and container DNS guides.

When you need the full Podman course in learning order, start at the Podman tutorial. When you already have an error string, use the routing table above and open the linked fix article for lab-tested remediation.