8  Troubleshooting: successes & failures

NoteLearning objective

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-agent pulled ~140 packages in a few seconds; pi --version reported 0.79.9.
  • Local tool-calling genuinely works. qwen3-coder-30b-a3b-instruct drove pi’s write and bash tools 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 -p runs 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 ps shows 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 32768

Bigger 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" bootstrap

And 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.

TipExercises
  1. Stop the LM Studio server (lms server stop), run a one-shot pi prompt against the lmstudio provider, and read the error pi reports. Restart the server and confirm the same prompt succeeds.
  2. Compare lms ps CONTEXT before and after reloading a model with a larger --context-length.
  3. Try a Gemma model in models.json and confirm it cannot complete a bash task; then switch back to qwen3-coder-30b-a3b-instruct.
  1. With the server stopped, pi cannot reach http://localhost:1234/v1 and 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”. After lms server start (and loading the model), the same one-shot prompt returns a normal answer.

  2. Inspect the CONTEXT column of lms ps while a model is loaded: by default it shows 8192, because LM Studio loads models with an 8192-token window regardless of pi’s models.json contextWindow (which only sets pi’s own compaction threshold). Reload with a larger window and lms ps now 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 32768
  3. Point models.json at a Gemma model and ask pi to do a bash task (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 to qwen3-coder-30b-a3b-instruct (a family with real tool support, alongside gpt-oss and llama3.3) and the same bash task completes with the expected on-disk side-effect.