Podman troubleshooting

Cannot connect to Docker daemon (using podman)

Podman has no daemon — this error means a script still calls docker expecting docker.sock. Use podman directly, set alias docker=podman, or enable podman socket for Docker API compatibility. Rootless socket: /run/user/$(id -u)/podman/podman.sock; set DOCKER_HOST=unix://... if a tool requires it.

Permission denied on volume (SELinux)

Common on RHEL/Fedora: container cannot read bind-mounted host dir. Add SELinux relabel: -v /host/data:/data:Z (private) or :z (shared). Check denials: ausearch -m avc -ts recent or journalctl -t setroubleshoot. Not SELinux? See UID mapping issues below.

Rootless volume UID/GID mismatch

Container runs as a mapped subuid; host files owned by a different UID fail. Check /etc/subuid and container user with podman inspect NAME | jq '.[0].Config.User'. Fix ownership on the host, run with --userns=keep-id, or set user: in Compose to align with the directory owner.

Container exits immediately

Same as Docker — check podman logs NAME and podman inspect NAME | jq '.[0].State.ExitCode'. Debug with podman run -it --entrypoint sh IMAGE. Rootless may fail if image requires capabilities rootless cannot grant — try rootful or adjust --cap-add.

Port bind failed (privileged port or in use)

Rootless cannot bind ports < 1024 by default. Use high ports (-p 8080:80) or sysctl net.ipv4.ip_unprivileged_port_start. "Address already in use": ss -tlnp | grep PORT. Format is host:container.

Rootless networking / cannot reach LAN

Rootless uses slirp4netns or pasta — different from bridge networking. Container may not be reachable from other hosts without port publish on the host IP. Test from host: curl localhost:PORT. For host ↔ container on same machine, published ports usually suffice. Check CNI config in ~/.config/cni/net.d/ (rootless) or /etc/cni/net.d/.

podman compose fails

Ensure podman-compose plugin or podman compose is installed (podman compose version). Some Compose features differ from Docker (e.g. certain volume drivers). Run podman compose logs SERVICE. Set COMPOSE_PROVIDER=podman if tools default to Docker.

No space left / storage full

Rootless storage: ~/.local/share/containers/; rootful: /var/lib/containers/. Audit podman system df and df -h. Prune: podman system prune -a. See disk volumes lab.

systemd service does not start container

User services need linger for boot without login: loginctl enable-linger $USER. Regenerate units after container changes with podman generate systemd --new. Quadlet: run systemctl daemon-reload after editing .container files. Check journalctl --user -u container-NAME or systemctl status NAME.

Image pull fails

Same causes as Docker: network, auth, TLS. Test podman pull alpine. Login: podman login registry.example.com. Rootless pulls to user storage — ensure home partition has space. Registries.config in /etc/containers/registries.conf.

Debugging workflow

1. Runtime mode

podman info | grep -i rootless
podman version
podman ps -a

2. Container state and logs

podman logs --tail 50 NAME
podman inspect NAME | jq '.[0] | {status: .State.Status, exit: .State.ExitCode, oom: .State.OOMKilled}'

3. Network, mounts, SELinux

podman port NAME
podman inspect NAME | jq '.[0].Mounts'
ausearch -m avc -ts recent 2>/dev/null | tail -5

Practice scenarios

Hands-on Podman scenarios on live Linux VMs: podman

Cheatsheet →