podspawnTroubleshooting
Common issues and how to fix them
This page covers the most common issues people hit when setting up and running podspawn, along with concrete fixes. When in doubt, start with podspawn doctor at the bottom of this page.
Most issues on this page are server mode problems (SSH, sshd, keys, user accounts). If you're using local mode (podspawn create, podspawn shell, podspawn run), skip to Container won't start or podspawn doctor.
Authentication problems (server mode)
Container problems
Permission problems
Feature-specific problems
podspawn doctor
The doctor command runs a series of checks and reports what's working and what's broken. It adapts based on your install type: without /etc/podspawn/config.yaml (local mode), it runs 6 checks covering Docker and local state. With the config file present (after server-setup), it runs all 11 checks including sshd validation.
# Local mode: 6 checks (Docker, state, disk, image)
podspawn doctor
# Server mode: 11 checks (adds sshd, keys, config dir)
sudo podspawn doctorReading logs
Podspawn writes logs to several places depending on the component. When something goes wrong, knowing where to look saves time.
How is this guide?