Troubleshooting
podbox doctor # diagnoses most issues, explains the fixpodbox doctor --fix # offers to fix them| Symptom | Fix |
|---|---|
| Container won't start | Container won't start |
| Hangs on startup | D-Bus proxy |
| GUI apps don't appear | Wayland socket |
notify-send, xdg-open, clipboard dead | Interceptors |
| Permission errors in mounted dirs | UID mismatch |
| SSH agent not forwarded | SSH agent |
| Stale image or failed build | Build |
podbox shell hangs | Shell missing |
| Commands hit the wrong container | Targeting |
Quick recovery
Won't start? Run this first:
podbox recover [NAME] # guided fix; --yes skips promptsSafe and idempotent: reloads systemd, reinstalls Quadlets, rebuilds the
image only if missing, then restarts. Never touches your home or config —
only podbox remove --all deletes those.
What doctor and recover actually do
podbox doctor groups checks into Host / Container / Integration and
ends with a plain-language Host exposure summary (network mode, D-Bus
rules, clipboard, agents, host-exec allowlist, extra mounts). Exits non-zero
when anything fails, so scripts can gate on it.
podbox recover walks four steps — daemon-reload + reset-failed, Quadlet
reinstall, image rebuild (only when missing), stop/start — confirming each
on a TTY.
Container won't start
podman ps -a --filter name=<name> # check container statepodbox logs # container outputpodbox enable --dry-run # inspect Quadlets without writingpodbox enable # safe to re-run (uses --replace)If Quadlets are installed, also:
systemctl --user status <name>.serviceD-Bus proxy fails or container hangs on startup
xdg-dbus-proxy is missing. Install it, or turn D-Bus off:
which xdg-dbus-proxy # should print a path[integration]dbus = false # if you don't need D-BusGUI apps don't appear / Wayland socket errors
The socket path is baked in at podbox enable time. If it changed (e.g.
after a reboot), regenerate:
echo $WAYLAND_DISPLAY # should print wayland-0 or similarpodbox enable # regenerate Quadlets (idempotent)podbox stop && podbox startInterceptors not working
notify-send, xdg-open, clipboard, and host-exec all go through the
guest daemon. If it can't reach the host socket, they're silently skipped.
podbox exec -- ps aux | grep podbox-guest # daemon running?podbox exec -- echo $PATH # should include /run/podbox/binpodbox exec -- cat /etc/environment.d/podbox.conf # PATH injection fileUID mismatch or permission errors
Host UID 1000 maps to container UID 999 (UserNS=keep-id, shifted by 1).
- Never
chowna bind-mounted dir from inside the container — it changes ownership on the host too. - Files owned by
nobody? The mount predates the UID mapping. Stop the container, fix ownership on the host, start again.
SSH agent not forwarding
Needs Podman ≥ 5.6 and:
[integration]ssh_agent = truepodbox doctor # checks Podman versiongrep ssh_agent ~/.config/podbox/<name>.tomlOn Podman 5.5 the socket path is baked at enable time — if $SSH_AUTH_SOCK
changed since (e.g. new login), re-run podbox disable && podbox enable.
Build fails or produces a stale image
podbox build --rebuildStill broken? Clear the build context and rebuild:
rm -rf ~/.local/share/podbox/<name>/podbox build --rebuildCustom-build Containerfiles regenerate from TOML on every build — package
and run.commands changes are picked up automatically.
Container starts but podbox shell hangs
The shell in container.shell isn't installed in the image. Add it to
[image.packages].install, then podbox build --rebuild.
Commands target the wrong container
Resolution order: positional [NAME] → -C → $PODBOX_CONTAINER →
active context → picker → single config → embedded default.
podbox use # show current contextpodbox use <name> # set itpodbox use --clear # clear it