8 Troubleshooting: successes & failures
You can recognise and fix the handful of issues that actually bite when running pi against a local MLX or LM Studio backend, drawn from a real setup session.
This chapter is a field guide: each item is something that either worked surprisingly well or went wrong during the verified setup behind this book.
8.1 What worked well
- Install is trivial and fast.
npm i -g --ignore-scripts @earendil-works/pi-coding-agentpulled ~140 packages in a few seconds;pi --versionreported0.79.9. - Local tool-calling genuinely works.
qwen3-coder-30b-a3b-instructdrove pi’swriteandbashtools through LM Studio, confirmed by on-disk side-effects the model could not fake (Chapter 5, Section 2.3). - No permission popups means clean scripting. One-shot
-pruns complete unattended. - Metal acceleration is automatic. Both backends build on MLX, which offloads the model to the graphics processing unit (GPU) out of the box;
lms psshows the loaded model and its device.
8.2 Failures and fixes
8.2.1 --mode json / --mode rpc produces no output
These modes read commands from stdin. Invoked with a bare prompt argument and no stdin attached, pi sees end-of-file (EOF) and exits silently. Use plain -p text mode for one-shot prompts; keep json/rpc for programs that hold a pipe open (Chapter 7).
8.2.2 Long sessions get truncated / the model “forgets”
LM Studio loads models with an 8192-token context window by default, no matter what you put in pi’s models.json contextWindow (which is only pi’s own compaction threshold). Check the CONTEXT column in lms ps. Fix by reloading the model with a larger context window, either in the app’s model-load dialog or from the command-line interface (CLI), e.g.:
lms load qwen3-coder-30b-a3b-instruct --context-length 32768Bigger context costs more memory.
8.2.3 A reasoning model errors or behaves oddly
Reasoning models such as gpt-oss need compatibility flags on the provider so pi does not send OpenAI-only features the local server rejects:
"compat": { "supportsDeveloperRole": false, "supportsReasoningEffort": false }(pi then uses the system role instead of developer and omits reasoning_effort.)
8.2.4 The first request is very slow
Cold-loading a model into memory dominates first-call latency: a 40+ GB model can take the better part of a minute before any output, then is fast while it stays resident. Pick a model size that fits your latency budget; load the model ahead of time with lms load <model> if you script it.
8.2.5 The model ignores the tools entirely
Not every model is trained (or templated) for tool-calling. Stick to families with real tool support: qwen3-coder, gpt-oss, llama3.3. Gemma-family models currently lack tool-calling templates and will not drive pi’s agent loop, however good they are at chat.
8.2.6 mlx_lm.server runs but pi’s tools never fire
The bare MLX server (mlx_lm.server, Section 2.2) serves text correctly but, as of mlx-lm 0.31.3, does not emit structured tool_calls: the model’s tool attempt comes back as plain assistant text (a fenced JSON block, JavaScript Object Notation) with tool_calls: null, so pi has nothing to dispatch and no file is created. This is the server, not the prompt or the model. Use mlx_lm.server only for generation-only workloads; drive pi’s agent loop through LM Studio (lmstudio provider), whose endpoint parses tool calls.
8.2.7 LM Studio: Invalid passkey, or lms get cannot find a model
Two first-run snags with the lms CLI. A stale ~/.lmstudio/bin/lms left by an older app build rejects the CLI with Invalid passkey for lms CLI client; re-bootstrap from the freshly installed bundle:
"/Applications/LM Studio.app/Contents/Resources/app/.webpack/lms" bootstrapAnd lms get author/repo fails with artifact … does not exist for arbitrary community models, because LM Studio lowercases the name and searches its own catalogue. Pass the full Hugging Face URL (uniform resource locator) instead: lms get "https://huggingface.co/mlx-community/…".
8.2.8 Picking a model for your RAM
A model needs roughly its on-disk size in free random-access memory (RAM) (Chapter 2). On 8–16 GB Macs use 3B–8B models; the 128 GB machine in this book ran 40+ GB models comfortably, but a 235B model (140+ GB on disk) exceeds even that and should be avoided there.
8.3 A note on security
pi is a local agent with no sandbox: its tools act with your user’s permissions. Project “trust” only governs whether project-local settings are loaded; it does not restrict what the model can ask the tools to do once you are working in a directory. Treat untrusted repositories accordingly. pi’s bundled docs/security.md is the authoritative statement.
- Stop the LM Studio server (
lms server stop), run a one-shot pi prompt against thelmstudioprovider, and read the error pi reports. Restart the server and confirm the same prompt succeeds. - Compare
lms psCONTEXTbefore and after reloading a model with a larger--context-length. - Try a Gemma model in
models.jsonand confirm it cannot complete abashtask; then switch back toqwen3-coder-30b-a3b-instruct.
With the server stopped, pi cannot reach
http://localhost:1234/v1and reports a connection error (connection refused) instead of hanging: the failure is immediate and names the endpoint, which distinguishes “no server” from “server up but model misbehaving”. Afterlms server start(and loading the model), the same one-shot prompt returns a normal answer.Inspect the
CONTEXTcolumn oflms pswhile a model is loaded: by default it shows 8192, because LM Studio loads models with an 8192-token window regardless of pi’smodels.jsoncontextWindow(which only sets pi’s own compaction threshold). Reload with a larger window andlms psnow reports the raised value. The larger window costs more memory.lms ps # CONTEXT shows 8192 lms load qwen3-coder-30b-a3b-instruct --context-length 32768 lms ps # CONTEXT now shows 32768Point
models.jsonat a Gemma model and ask pi to do abashtask (for example, create a file). The model will not drive the agent loop: Gemma-family models currently lack tool-calling templates, so the tools never fire and no file is created, however fluent the chat reply looks. Switch the model back toqwen3-coder-30b-a3b-instruct(a family with real tool support, alongsidegpt-ossandllama3.3) and the samebashtask completes with the expected on-disk side-effect.