Troubleshooting
Common errors, configuration checks, and issue-report information.
Use the error message and the failing component to narrow down a problem. The sections below cover common startup, model, browser, resource, and Git failures.
Startup#
Check the release architecture and asset. Unsigned builds may require approval through the OS security interface.
For source builds, confirm the Node and pnpm versions, dependency installation, and required build targets. See Development. Preserve logs before removing a profile or reinstalling.
Providers and models#
| Error or symptom | Check |
|---|---|
| Authentication rejected | Repeat the provider sign-in/key flow and check the storage state. |
| Unknown/unavailable model | Select an identifier offered by that provider or server. |
| Rate limit or credit error | Check the provider account; not all limits are displayed in pi-kit. |
| Connection refused | Check the process, API base URL, prefix, and port. |
| Text generation works but tools fail | Check model tool support and the server's template/configuration. |
| LiteLLM catalog is empty | Check the proxy URL, key permissions, and advertised chat models. |
For file/configuration failures, see Local models. Download completion and model availability are separate states: the existing llama-swap service must read the configuration and serve the model.
Browser and captures#
The native browser requires desktop mode. In Artifacts, check the project server's address and whether it is still running. Non-HTTP(S) URLs and internal pi-kit origins are blocked. Permissions and downloads are not supported.
Navigation invalidates element references and inspection selection. Obtain a new snapshot or select the element again. Switching threads during capture can cancel attachment insertion.
For oversized selected regions, zoom out or use whole-page capture. Whole-page capture can change viewport-dependent layout; compare a viewport image when needed. A blank/failed capture should be reported separately from the page's rendered state.
Packages and skills#
Check the active project, resource scope, trust decision, enabled state, and installation result. For a skill, check the
SKILL.md location and frontmatter, then reload resources.A missing tool or command can also result from the executable PATH available to the desktop backend. Test a stable absolute executable path to distinguish this from a server/configuration problem.
Git and worktrees#
| Condition | Resolution |
|---|---|
| Dirty checkout blocks a branch switch | Inspect changes and commit or stash them. |
| Another worktree holds the branch | Use that checkout or choose a different branch. |
| New worktree does not exist yet | Placement is applied at first Send. |
| Setup script fails | Check its command, dependencies, environment, and copied files. |
| Sync produces conflicts | Resolve them, check status, and run tests before merging. |
| Removal is refused | Inspect uncommitted files and other threads using the directory. |
Navigating to an earlier conversation turn does not roll back files. Use the selected Changes source or Git to check the working tree.
Learning replay#
Verification requires the learning package, an outcome with available base/head commits, a usable model, and acceptable project-resource trust. A discarded draft must be reopened before verification.
Setup failures, unanswered tool questions, timeouts, and stopped runs appear in the report. The verification thread provides a transcript of the replay; inspect it when the result is incomplete or differs from the outcome.
Report an issue#
Include:
- App version and OS/architecture.
- Desktop or web-only mode.
- Reproduction steps and expected/observed behavior.
- Relevant error text and logs.
- A screenshot, if relevant and available.
- Whether the problem reproduces in a minimal project.
Advanced → Diagnostics provides application information. The repository documents macOS logs under
~/Library/Logs/pi-kit/. Remove credentials, recovery values, and unrelated private data from reports.