Troubleshooting

podbox doctor         # diagnoses most issues, explains the fix
podbox doctor --fix   # offers to fix them

Quick recovery

Won't start? Run this first:

podbox recover [NAME]        # guided fix; --yes skips prompts

Safe 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.

Container won't start

podman ps -a --filter name=<name>      # check container state
podbox logs                            # container output
podbox enable --dry-run                # inspect Quadlets without writing
podbox enable                          # safe to re-run (uses --replace)

If Quadlets are installed, also:

systemctl --user status <name>.service

D-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-Bus

GUI 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 similar
podbox enable                            # regenerate Quadlets (idempotent)
podbox stop && podbox start

X11 apps don't start

For X11 support, enable Wayland and install both host dependencies: xwayland-satellite and Xwayland. Then run:

podbox doctor
systemctl --user status <name>-x11.service

If the satellite is missing, install it with your distribution's package manager or cargo install xwayland-satellite where no package is available, then rerun podbox enable. The X11 bridge is per-container; X11 clients in a container share its display, but the bridge does not use the host X socket.

Interceptors 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/bin
podbox exec -- cat /etc/environment.d/podbox.conf   # PATH injection file

UID mismatch or permission errors

Host UID 1000 maps to container UID 999 (UserNS=keep-id, shifted by 1).

• Never chown a bind-mounted dir from inside the container — it changes ownership on the host too.
• Foreign-owned entries inside the home (usually ~/.cache, left by a run under a different userns mapping) break writes: mise cannot create its cache, fish cannot write history. The guest repairs them automatically on the next start — one podbox-guest: home: repaired ownership of N entry(ies)line in the logs — andpodbox doctor` reports the state before you start. Read-only host shares (fonts, icons, themes) keep the host's ownership and are never touched by the repair.

SSH agent not forwarding

Needs Podman ≥ 5.6 and:

[integration]
ssh_agent = true

podbox doctor                             # checks Podman version
grep ssh_agent ~/.config/podbox/profiles/<name>.toml

On 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.

adb: no permissions / device unauthorized

With [integration.hardware] usb = true:

• podbox doctor tells you whether any USB node is accessible to your user. If none is, install the device's udev rules (android-tools / android-udev for phones) or add yourself to the owning group (plugdev), then replug.
• Only one adb server can claim a device: adb kill-server on the host before listing devices in the box.
• "unauthorized" means the phone is waiting on the RSA prompt — accept it on the device and run adb devices again.

Build fails or produces a stale image

podbox build --rebuild

Still broken? Clear the build context and rebuild:

rm -rf ~/.local/share/podbox/<name>/
podbox build --rebuild

Custom-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 context
podbox use <name>           # set it
podbox use --clear          # clear it

Mount propagation errors (nested mounts not visible)

Symptom: bind mounts or nested mounts created inside the container are not visible on the host, or podman reports mount-propagation errors.

Cause: the root filesystem / is not marked shared, so mount events do not propagate across the mount namespace boundary.

Fix: check the current propagation mode and make the root shared:

findmnt -o PROPAGATION /
sudo mount --make-rshared /

To make it persistent across reboots, add the mount --make-rshared / step to your boot sequence (for example via a systemd oneshot unit).

Slow builds or overlay errors in rootless mode

Symptom: image builds are very slow, or fail with overlay/fuse-overlayfs errors when running rootless podman.

Cause: podman is using the fuse-overlayfs storage driver instead of the kernel's native overlay, usually because the kernel is older than 5.13 or user-namespace support is disabled.

Diagnose:

podman info --format '{{.Store.GraphDriverName}}'

Fix: upgrade to a kernel >= 5.13 with user namespaces enabled, then reset the storage:

podman system reset

After reset, podman info should report overlay as the graph driver.

Exported app missing from the application menu

Symptom: podbox export succeeded but the exported application does not appear in the desktop menu.

Cause: the generated .desktop file fails TryExec (the binary is not on PATH inside the container or the shim is stale), or the desktop database is out of date.

Fix: validate the exported file and refresh the database:

desktop-file-validate ~/.local/share/applications/<name>.desktop
update-desktop-database ~/.local/share/applications

Also verify the TryExec line points at an executable that exists.

Prompt shows "I have no name!"

Symptom: a shell inside the container prints I have no name! instead of the username.

Cause: the image creates a user whose UID collides with an existing UID in the image's /etc/passwd, so NSS cannot resolve the name.

Diagnose inside the container:

podman exec <container> getent passwd $UID

Fix: rebuild with a non-colliding UID, or set container.user / the image's user explicitly in the TOML definition.

setlocale warnings

Symptom: commands print warnings such as bash: warning: setlocale: LC_ALL: cannot change locale.

Cause: the locale requested by the host (or by [container.env]) is not generated inside the image.

Diagnose inside the container:

podman exec <container> locale -a

Fix: add the locale packages to [image.packages].install (for example glibc-langpack-en on Fedora or locales on Debian/Ubuntu) and rebuild, or drop the offending LC_*/LANG value from the config.

Notifications, clipboard or xdg-open do nothing

Symptom: notify-send, clipboard copy/paste or xdg-open inside the container silently does nothing.

Cause: the capability was not negotiated during the guest↔host handshake, or the host socket service is down.

Diagnose:

systemctl --user status podbox-<name>.socket

Fix: ensure the socket unit is active and re-run podbox enable <name>. The guest sends a Hello on connect; a successful handshake is required before any interceptor request is served.

GPU apps fail on NVIDIA

Symptom: GPU-accelerated applications fail to start inside the container on an NVIDIA host.

Cause: no CDI (Container Device Interface) specification was generated for the NVIDIA devices, so podman cannot inject them.

Fix: generate the CDI spec and re-enable the container:

sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml
podbox enable <name>

See the NVIDIA container toolkit documentation for details.