Troubleshooting #
On this page
Start with the checker. It looks at your configuration, the proxy, sign-ins, ports, remote control and the sandbox, and says what to do about each problem it finds:
maple-harness doctor # add --fix to repair file permissions and stale files
maple-harness doctor --report bug.txt # a redacted bundle to attach when you ask for help
Two commands inside a session answer most of the rest:
/proxy where the proxy is, whether it answers, how many models it serves
/context what the model can see: window size and how full it is
maple-proxy serve --logs=true shows every request and the reason behind every failed one.
In plain words #
- Start with the checker.
maple-harness doctorlooks at everything and says what to fix, in plain words. - Then look here. Find the symptom below; each has the fix. On the setup page, What's configured on the Overview marks anything that needs attention, with a link to where it is set.
The proxy #
The agent says the proxy is unreachable. Nothing answers at the configured address. /proxy shows where
the agent is looking, and /proxy start starts one. This usually means server.openai_compat in
config.yaml differs from where a proxy was started.
The setup page at 127.0.0.1:11539 does not load. Check the proxy is running. server.webui in
config.yaml sets its address, and an empty value turns the page off. The page only listens on this machine;
from another device, use Control it from your phone.
A CI job or script stops with "This session cannot ask you, so it did not start". The run (--prompt, --rpc,
serve, or no terminal) found a proxy on this machine that it cannot verify as yours: one in a container, run as
another user or with another settings folder, or your own still on an older release. It exits with status 1. Start
the proxy in the job as the same user (or let the harness start it), run maple-harness proxy restart after an
update, or follow CI jobs and containers for a proxy you do not start.
Port already in use. The defaults are 11535, 11537 and 11539. Find what holds one with
lsof -i :11539, then stop it or change the address under server: in config.yaml.
Signing in #
Copilot sign-in never finishes. Open the link it printed and enter the code within ten minutes, then run
maple-harness auth login github-copilot again. A 403 means the account has no Copilot seat, or the grant
was revoked; signing in again is the first thing to try.
"This account has no chat models enabled for Copilot". The account is signed in but nothing it lists is usable. On an organisation's seat, check the Copilot policies your organisation set.
Copilot: model_not_supported. The free plan does not let an account call most models by name; they are
served through auto mode. Signing in configures this for you, so run maple-harness auth login github-copilot
again to refresh, and only the models that work are written. Remove any model you added by hand that fails
this way.
Anthropic: "credit balance too low". The key is valid and the account has no API credit. Add credit under Plans and Billing in the Anthropic Console. API credit is separate from a claude.ai or Claude Code subscription, which is not an API key.
Anthropic: "rejected that API key". Anthropic refused the key, so nothing was stored: it is not valid, or it has expired, been disabled or been deleted. Check it was copied whole, or create a new one in the Claude Console.
Anthropic: "Admin API key" or "subscription sign-in token". That credential is the wrong kind for a proxy and was refused before it was sent anywhere. Use an ordinary API key limited to one workspace. See Sign in.
Anthropic: "not limited to one workspace". Choose the workspace the key's requests run in (the setup page
lists them; on the command line, maple-proxy auth login anthropic --workspace wrkspc_...), or use a key
limited to one workspace.
Anthropic: "API usage limits". The organization reached its monthly spend cap, or a spend limit you set for it or for a workspace. Requests are refused until it resets or you raise it in the Claude Console; waiting a minute does not help. The proxy treats it as out of quota, so a fallback you configured is used.
The quota meter is missing. It appears only when the current model's provider has a metered account. It is absent for local models. Sign in first, and note that before the first request only what is left is known.
Models #
The context window shows 0, or history is trimmed too early. A window of 0 means unknown. Leave
context_window out of config.yaml so the proxy asks the server, and check /context. If the server
reports nothing, set it by hand.
A local model repeats itself or stops without finishing. Small models do this. Use them for scoped work,
such as a function, a file or a fix, start a fresh session per task, and use /compress when one grows long.
A slow local model times out, or "produced no output within". A local model server can take many minutes
to send anything when it writes a long file through a tool call: some servers send a tool call only once it is
complete, and at about ten tokens a second a few thousand tokens take a while. The proxy waits 30 minutes for a
model server you run (10 for a cloud service), and Maple Harness waits as long as the proxy. If it still runs out,
the request is asked again at most twice and then the turn stops with a message that names the model. Raise
first_output_timeout_seconds on that provider (setup page: Proxy settings, Waiting for a slow model), and
first_output_timeout_seconds in the harness settings if you set that one; or use a smaller or faster model, or
ask for the work in smaller pieces.
A small local model keeps writing and never stops. Set max_output_tokens on the model in the proxy's
configuration. For a model server you run, the proxy sends it as max_tokens and, if the server ignores it, ends
the reply itself at that limit and stops the server; the harness then treats it as a reply cut at its limit. The
server's own limit (for example llama.cpp's -n) works too.
The model says it "can't build the whole project in one run". Small and cheap models sometimes decline a long
task they are able to do. Maple Harness answers once with a nudge to start step by step, and says so
("continuing — the model declined a task it can do"). If the model declines again it tells you which model it
is and suggests a stronger one with /model <name> (or pinning models with auto_model_map, see
Choose a model). With /model auto, a model that declined is skipped for the rest of the session.
Auto keeps picking a model that declines. Auto avoids models known to decline long tasks and remembers ones
that do (maple-harness doctor lists them; maple-harness cleanup --declines --yes forgets them). To choose
yourself, use /model <name>, pin models with auto_model_map, or add patterns to auto_avoid in config.yaml.
A model you choose yourself is never blocked by any of this.
Detect models finds nothing. The address must include the API prefix (/v1, or /api/v1 for Lemonade),
and the server must be running. Choose the matching type in the picker so its usual address is filled in.
Find local models finds nothing. It only asks this computer (127.0.0.1 and ::1), on each server's usual port, and waits about a second and a half. A server on another port, on another machine or still loading a model is not found: add it by hand. See Connect a model server.
"Stopped: the model kept describing steps without taking them." Maple Harness carries a turn on by itself when
the model describes its next step instead of taking it, but not forever: at most 50 times for one message
(harness.max_auto_continues), and not again once the model, asked to carry on, describes the step again instead
of doing it. The model's last report is left as the answer. Type "continue" to carry on, or say what to do next.
An answer is folded away and a line starting with » says check: …. Maple Harness checked the model's
answer against what really happened in the session and found something wrong with it: for example it reported
Lint: npm run lint → pass though the lint never ran, or named a file that does not exist. The harness folds that
answer to one line, says what it found, and asks the model for a corrected answer, which is the one left on screen,
followed by a line such as » checked: npm run lint ran and passed. Nothing is thrown away: click the folded line,
or press ctrl+o, to read it.
In more detail: lines starting with » are always the harness's own, never the model's or yours. » check: …
means an answer was sent back; » checked: … says what became of each command it named (ran and passed, ran and
failed, or no longer claimed); » continuing: … means the model described a next step without taking it and was
asked to carry on (harness.disable_auto_continue turns that off). The note the model gets asks for its whole
answer again, corrected, and not for a reply to the check. If a model replies to the check anyway ("Confirmed, I
ran it"), and every command it had named has now run and passed, that reply is folded instead and the earlier
answer is shown again as the final one, under "the answer stands". If a command failed, the model's newest answer
stays as it is. Every client ends on the same answer: the remote app, --rpc, serve, and --prompt, whose output
then ends with that answer printed again after » final answer: on the error stream.
Cost #
A run cost more than I expected #
Type /cost. It shows what the session has spent, the last few requests with how much of each was served from
the provider's cache, and where the input goes. A request marked "low cache hit" or "model changed" is where the
cache was lost: a new model starts with a cold cache. To keep it, use /model fixed (or pick a model and leave
/model auto off), and try a lower reasoning effort with /effort low on models that think a lot. Long histories
already keep their model in /model auto.
The agent keeps retrying the same failing command #
When the same problem fails again and again, Maple Harness steps in. After three similar failures it adds a note
to the result telling the model to stop trying variations, say what it is assuming, check that with a cheap
read-only command, and choose a different approach. After six, it ends the turn with a summary of what was tried
and the last error, and asks you for guidance: tell it what to try, or say continue.
Only the same failure counts. A different failing test each time is progress and is left alone, and a test that
fails twice and then passes is not counted. A --prompt run that stops this way exits with status 3, so a script
can tell it from success (0) and from an error (1). A phone or desktop notification says "Needs guidance".
A failing command's long output (a full test report) is shortened to the start, the lines that say what failed, and the end; the exit status is always kept, and the whole output is saved to a temporary file whose path is shown.
To change or turn this off, in config.yaml:
harness:
loop_guard: { mode: stop, warn_after: 3, stop_after: 6 } # mode: off | warn | stop
tool_output: { failed_max_lines: 120 } # 0 keeps failing output whole
Installing and updating #
checksum mismatch. The installer stops and leaves the existing files untouched. A truncated download is
the usual cause; run it again.
permission denied writing to /usr/local/bin. Use --install-location ~/.local/bin, or run the installer
with sudo.
macOS says a downloaded binary cannot be opened. Binaries downloaded by hand are not notarised yet. Right-click and choose Open, or use the installer, which avoids this.
Remote control #
The phone cannot reach the address. Check both devices are on the same Tailscale network (or the same local network for a LAN address) and that a firewall is not blocking port 11541.
Pairing shows a link that does not load. The gateway may have stopped. /remote pair starts it again; or
run maple-harness gateway start.
A phone lists sessions but + New session is refused. No folder is allowed yet:
maple-harness gateway workspaces add <dir>.
A session does not appear in the phone's list. Share it with /remote in that session.
The gateway or proxy is gone after a reboot. Install them as services:
maple-harness service install. See Keep it running in the background.
Notifications do not arrive with the page closed. That needs a trusted HTTPS certificate; see
Control it from your phone. maple-harness doctor says which certificate
the gateway is using.
429 from the proxy on another machine. Requests from other machines are rate-limited. Slow down, or ask
the owner to raise server.rate_limit in config.yaml.
The shell sandbox #
/sandbox says bubblewrap is missing, or installed but not working. It is optional; the install command for
your system is in Install. "Installed but does not work"
usually means unprivileged user namespaces are blocked, for example in a container. Until it works, commands
run uncontained.
A command fails inside a shared session because it has no network. While a session is shared for remote
control, the shell has no network unless you allow it: /sandbox network allow, or set
harness.sandbox.network: allow in config.yaml.
sh: fork: Resource temporarily unavailable. Fixed in current builds; update with maple-harness update
and restart the agent.
Disk space #
The configuration directory (~/.config/maple-harness) holds saved sessions, memory notes and logs. To see how
much it uses and clear old sessions, run maple-harness cleanup --help.
More help on other pages #
Some pages have their own troubleshooting section for the feature they cover:
- Language servers: Troubleshooting: a server is not found, or its errors do not show up.
- Search by meaning: When something goes wrong.
- The shell sandbox: When a command is blocked.
- Control it from your phone: If it does not work.
- Keep it running in the background: Troubleshooting: the proxy or gateway as a service.
- Use it with herdr: If the pane does not pick it up.
- Connect a model server: Check it.