Start with the smallest layer that can explain the symptom. Preserve dirty work and logs before restarting or forcing a stop.
Run the first checks
Check local processes, machine readiness, and recent logs before changing state:
podium is not found after installation
The installer updates future login shells. Open a new shell or run:
If that fails in a new shell, add ~/.local/bin to the startup file your shell reads.
A machine cannot pair or reconnect
Pairing codes are single-use and expire after one hour. Generate a new command in Settings, then Machines, then Add machine.
The daemon connects outward to the server. Confirm that it can resolve and reach the configured server URL. If a Cloudflare quick-tunnel URL changed, update the joined machine:
A harness is missing or logged out
Re-run the machine probe:
Install or authenticate the native harness on that machine. Podium does not replace the harness’s own account login.
An issue cannot start
Check these conditions:
- The issue is not blocked by an open dependency
- The selected machine is online and usable
- The repository exists there or has a cloneable origin
- The selected harness is installed and logged in
- No conflicting worktree or branch already owns the target path
Use podium issue show your_issue_ref and podium machine show your_machine_name to inspect the exact state.
A session appears unresponsive
Inspect its structured state and a short transcript window before stopping it:
Do not force-stop a session with unsaved changes. If the phase is retryable error, fix the reported cause and run podium session continue your_session_id.
Collect diagnostics safely
Export recent crash events for support:
Review the file before sharing it. Logs can contain repository paths, prompts, command arguments, hostnames, and error details. Last modified on September 16, 2026
