Most PiLot Studio problems fall into one of five buckets: VS Code's runtime, the pi binary, provider credentials, project trust, or a local native dependency. Work through the matching section before opening an issue.

First checks

Run these in VS Code's integrated terminal:

node --version
pi --version

Expected:

Node 22.19.0 or newer in the extension host.
PI 1.4.0 or newer.
VS Code 1.105 or newer.

If pi works in an external terminal but not in VS Code, VS Code's PATH is different. Restart VS Code after changing your shell profile, or set pi-agent.binaryPath to the absolute executable path.

PI is not detected

Symptoms: the panel opens with a "could not locate pi" error, or sessions fail to start.

Run pi --version in the VS Code terminal.

If it fails, install PI:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

If it works externally but not in VS Code, set pi-agent.binaryPath to the output of:
```
which pi        # macOS / Linux
where pi        # Windows PowerShell
```
Reload the VS Code window.

PiLot Studio rejects shell metacharacters in binaryPath because the value can come from a workspace's .vscode/settings.json. Use a plain absolute path.

PiLot Studio does not activate

If VS Code shows an activation error instead of the sidebar:

Check the VS Code version. 3.0 requires 1.105+ because PI 1.4 requires Node 22.19. The extension shows a readable error and stops on older versions.
Check the PI SDK version. The loader refuses a globally installed PI SDK older than 1.4.0. Run pi update, then reload.
Check for a broken global install. If pi --version fails, reinstall PI.
Use the Extension Host log. Help → Toggle Developer Tools → Console, and the Extension Host output channel, show loader errors.

You can also open the PiLot Studio Diagnostics output channel, but it only exists after activation has proceeded far enough to create it.

No model response

Open Providers and confirm the selected provider shows API key valid or OAuth active.
Open the model picker and confirm a model is selected.
Send a one-line prompt with no attachments and no @ mentions.
Check the provider's status page and your account limits.
If the response is a 401/403, re-enter the key or sign in again.
If it is a 429 or timeout, wait and retry; some providers rate-limit aggressively.
If a local endpoint is selected, confirm the server is running and the base URL ends with the OpenAI-compatible path (for Ollama, usually /v1).

PiLot Studio does not proxy requests, so provider outages and account issues appear exactly as they would in the Pi CLI.

The model picker is empty

The picker only lists models from configured providers.

Add a key or OAuth credential in Providers.
Use Refresh in the Providers header.
For a custom provider, confirm the base URL and the model IDs. Fetch available models queries <baseUrl>/models.
If you just refreshed an online catalog, wait for the request to finish and reopen the picker.

A key disappears after reload

3.0.0 writes panel-entered keys to PI's auth.json as well as PI's credential store, so they survive a window reload. If a key still disappears:

Check that pi-agent.agentDir points at the same directory the CLI uses.
Check that auth.json is writable and owned by your user.
Do not edit auth.json while a save is in progress; the extension writes atomically and leaves an unparseable file untouched.
Re-enter the key and use Verify to confirm it.

MCP server is not listed

Open the MCP Servers tab and click Refresh.
For a project server, confirm the workspace is trusted. A banner appears when .pi/mcp.json is being ignored.
Check the file path: global servers live in <agentDir>/mcp.json; project servers in <workspace>/.pi/mcp.json.
Validate the JSON. The panel reports malformed entries; a broken top-level object can hide the whole file.
If a project entry only overrides a global server, the global server must exist first.
Run pi mcp list --json in a terminal to see what PI itself reports.

Choose Sign in on the server card. This runs pi mcp login <name> --timeout 300 and opens the provider's browser flow. If the browser does not open or the flow times out:

pi mcp login <name>

Then refresh the panel. Sign out removes the stored OAuth credential.

MCP tools are missing or codemode is inactive

A server with hidden exposure is registered but unreachable by the model.
A codemode server needs codemode active. Check Preferences → MCP & Codemode → Auto-enable Codemode.
If you want codemode in every new session, enable Codemode by default (adds +codemode to defaultTools).
Project-level defaultTools and codemode values override global ones in a trusted workspace.
Light Mode skips MCP, codemode, and tool-search factories. Turn Light Mode off.

Voice dictation is unavailable

Check pi-agent.voice.enabled and the microphone button.
Grant VS Code microphone permission in your OS privacy settings.
The first use needs a model download. If the download fails, retry; partial files are removed.
On Linux, install ALSA: libasound2 (Debian/Ubuntu) or alsa-lib (Fedora/RHEL). A missing shared library is reported explicitly.
On macOS or Windows, confirm the extension installed the helper for your architecture (x64 or arm64).

Dictation is local after the download. If you are offline, the model must already be cached in <agentDir>/voice-models/.

Sessions are in the wrong place or missing

pi-agent.agentDir changes where PI stores auth, models, settings, and sessions. Reload the window after changing it.
pi-agent.sessionDir adds a subdirectory inside the agent directory.
History is scoped to the current workspace. Open the folder that owns the session.
A session deleted from History is deleted from disk. Restore it from a backup if you need it.

Fork fails

Forking requires a session file on disk. A brand-new in-memory session may not have one yet; send a message first, then fork. The original session is never modified by a fork.

Export does not produce the expected format

In 3.0.0, HTML and JSONL exports are reliable. The Markdown option in the dialog routes through the HTML exporter, so the .md file contains HTML. Use HTML or .jsonl until this is corrected.

Native addon errors

If better-sqlite3 fails to load after a VS Code or Node upgrade, run:

PiLot Studio: Rebuild Native Addons

Then reload the window. The command rebuilds the addon against the current extension-host Node version. If the rebuild fails, include the terminal output in your report.

Updates fail

pi-agent.offline skips PiLot's update and package checks.
The update command opens a terminal running pi update; check that terminal's output.
Package updates use pi update --extensions.
If the PI update fails, reinstall PI with the npm command and reload.
PiLot Studio itself updates through the VS Code Extensions view.

Provider-specific errors

401 / invalid API key — the key is wrong, expired, or scoped to a different endpoint.
403 — the key lacks access to the selected model, or the provider requires an organization/project header.
404 / model not found — the model ID is not available at that endpoint. Re-fetch the model list or edit models.json.
429 — rate limit. Wait, reduce concurrency, or switch models.
Context length exceeded — compact with /compact, start a new session, or choose a model with a larger window.
Image input rejected — the selected model does not accept images.

Collecting diagnostics

Set pi-agent.diagnostics.enabled to true.
Reproduce the problem.
Run PiLot Studio: Show Diagnostics Log to inspect the output.
Run PiLot Studio: Export Diagnostics Log… and save the file.
Include the log with your issue, after reviewing it for sensitive paths or code.

The log is local and capped at 2,000 lines. It is off by default.

Getting help

Open an issue at github.com/Printaga/PiLot/issues with:

PiLot Studio version, VS Code version, OS, and pi --version.
The exact steps to reproduce.
The error text from the chat or the diagnostics export.
Whether the same operation works in the Pi CLI.

The Pi CLI documentation is authoritative for PI behavior that PiLot Studio only surfaces, such as provider catalogs, MCP command syntax, and package resolution.