Troubleshooting & FAQ

Common issues when installing and running the Potpie CLI, and how to resolve them.

Diagnostics first

When anything misbehaves, start with these two commands. They surface most problems on their own:

potpie doctor
potpie status --host

• potpie doctor runs local diagnostics for the daemon, backend capabilities, and skill drift.
• potpie status --host checks daemon, pot, graph, and skill readiness.

CLI exit codes

When scripting or debugging, the CLI's exit code tells you the failure class:

Code	Meaning	Typical cause
0	Success	—
1	Command or validation failure	Bad arguments, invalid input
2	Daemon/API/dependency unavailable	Daemon not running, backend unreachable
3	Partial/degraded result	Some data returned, some failed
4	Auth/permission failure	Expired or missing credentials

Common issues

command not found: potpie after install

The install location isn't on your PATH.

• If you installed with uv tool install potpie, run uv tool update-shell and restart your terminal.
• If you installed with pip install --user potpie, ensure your user bin directory (e.g. ~/.local/bin) is on PATH.

Daemon not running (exit code 2)

Most commands route through a local daemon. If it isn't running:

potpie daemon status
potpie daemon restart

If the daemon won't start, inspect its logs:

potpie daemon logs --follow

Python version mismatch

Potpie requires Python 3.10+. Check your version:

python3 --version

If it's older, install a newer Python (uv can manage this for you) and reinstall the CLI.

Integration auth expired (exit code 4)

Re-authenticate the affected provider, then verify:

potpie github login    # or: linear / jira / confluence
potpie status --verify

--verify performs lightweight API checks to confirm credentials actually work.

No active pot / pot not found

Every command runs against the active pot. List pots and select one:

potpie pot list
potpie pot use <id-or-name>

If you have no pots at all, re-run setup:

potpie setup --repo .

Graph not ready / queries return nothing

Check graph readiness:

potpie graph status

The graph is populated through agent-led ingestion, not by source add alone. Register the source and let your configured harness ingest context when a task requires it.

FAQ

Do I need to run a separate ingest command?

No. The CLI registers sources, and the configured agent ingests or updates project context when the task requires it. There is no manual ingest step on the happy path.

Does Potpie send my code to the cloud?

Not by default. Graph state stays local unless you explicitly run potpie login and select a managed pot, or run an explicit potpie cloud push. See Context Graph → Local vs. managed.

Which coding harnesses are supported?

Claude Code, OpenAI Codex, Cursor, and OpenCode. Install or refresh skills for one with:

potpie skills install --agent <agent>

How do I open the visual graph explorer?

potpie ui

This opens a local graph explorer served by the daemon in your browser.

How do I completely reset a pot?

potpie pot reset --confirm

Destructive commands require --confirm (or interactive confirmation).

Still stuck?

• GitHub Issues — bugs and repository-scoped requests
• Discord — community discussion and support