// Use when the Potpie CLI is failing — especially around API key, URL config, 401, 404, pot scope, or search/ingest HTTP errors.
Use when an agent needs project context from the context engine through MCP tools. Covers context_resolve recipes for feature, debugging, review, operations, docs, and onboarding without adding separate context tools.
Use when the task involves running, explaining, or troubleshooting the Potpie CLI. Covers doctor, login, pot management, search, and ingest commands.
Use when the task is about pot resolution: pot use, env maps, git origin parsing, repo-to-pot mapping, or search/ingest scope inference.
| name | potpie-cli-troubleshooting |
| description | Use when the Potpie CLI is failing — especially around API key, URL config, 401, 404, pot scope, or search/ingest HTTP errors. |
Use this skill for failures, broken setup, or unclear runtime behavior in the Potpie CLI.
potpie doctor # human output
potpie --json doctor # machine-readable
Check:
potpie_health_ok — server reachablepotpie_auth_ok — API key validactive_pot_id — pot is setPotpie API not configured
Set POTPIE_API_URL (or POTPIE_BASE_URL) and POTPIE_API_KEY in your environment, or run:
potpie login <your-api-key> --url http://your-host:port
401 Invalid API key
The stored key is wrong or expired. Re-login:
potpie login <new-api-key> --url http://your-host
Env var POTPIE_API_KEY overrides stored credentials.
404 or Unknown pot
The pot UUID is not accessible for that user. Check:
potpie pot pots # list pots you have access to
potpie pot use <correct-id>
Pot scope required
No active pot and cannot infer from git or env. Fix:
potpie pot use <uuid>
# or pass explicitly
potpie search <uuid> "my query"
Health OK but auth fails
GET /health passes but /api/v2/context/pots returns 401. The base URL is correct but the API key is wrong.
Wrong base URL
/api/v2 in the base URL — use origin only, e.g. http://127.0.0.1:8001.Server returns 503
Context graph may be disabled on the host. Check server logs.
409 duplicate_ingest
Episode already exists with that idempotency key. This is safe — re-ingesting the same content is idempotent.
--json to get structured output for scripting: potpie --json doctor | jq .potpie_auth_ok--verbose for full Python tracebacks on unexpected errors.