Troubleshooting

🔧 Troubleshooting

Start here when something does not work. If the answer is not below, open a question or a bug report.

🧾 First: find the log

In a portable install the log lives under data/user-data/logs/, in the newest folder. Paste the first error, not the last — the last one is usually just a consequence.

🪟 Windows warns on first run

The binaries are unsigned today, so SmartScreen warns once. Verify the SHA256SUMS.txt that ships with the release, then choose More info → Run anyway. That is expected, not tampering.

😶 I open it and the agent says "Language model unavailable"

No provider is connected yet. Run PiCode: Set up PiCode (or open settings → PiCode → Providers), connect a provider and pick a default model. See Pi Inside.

🔐 A provider sign-in fails

• The OAuth flows belong to Pi, and PiCode shows Pi's own dialogs. If a browser does not come back, retry from Set up PiCode.
• On Windows, the Anthropic login falls back to a free loopback port when its usual port is taken by Hyper-V or WSL. Nothing to configure.
• A key-based provider: check the key is in PiCode's own profile and not only in an environment variable of another shell.

🧩 An MCP server will not connect

• Check the server's own command and arguments first — PiCode bridges editor MCP tools to pi, it does not replace the server.
• A server that needs a sign-in asks for it in the MCP page. Sign in there; the credential is stored in PiCode's profile.
• Toggle the server off and on to rebuild the session after editing it.

🎨 A theme will not install

It probably exists only on the Microsoft Marketplace. PiCode installs from Open VSX. Try the theme's Open VSX listing, or pick another in the gallery.

⬆️ No update is offered

• Check the update feed of your channel is reachable (updates/<channel>/win32/x64/user/latest.json on the channel's branch).
• A newly published release becomes available to installed editors after a short rollout delay.
• Updates ship through GitHub Releases; the in-product auto-replace is disabled on purpose.

🧱 The build fails

• MSB8040 — the Visual Studio Spectre libraries are missing.
• Out of memory while packing — packing asks for more than 6 GB of heap. On an 8 GB machine use NODE_OPTIONS="--max-old-space-size=5632".
• On Ubuntu 24.04 — systemd-oomd can kill the whole build under memory pressure without printing "Killed". Stop it before building.
• node --version does not match .nvmrc — the build expects the pinned Node version.
• Run ./dev/build.sh -o first — it checks the tree in seconds and compiles nothing, which rules out most of the guesswork.

The full dependency list and the build traps are in Building PiCode and CI and Releases.

♻️ Everything is broken: start clean

Your configuration lives in one folder. Move data/ aside (do not delete it yet) and reopen PiCode — a fresh data/ is created. Put the old folder back to restore your setup.

🆘 Still stuck?

• A question: open a question.
• A bug: open a bug report.
• A security problem: use the private security advisory form — never a public issue.