Source: https://sparetokens.ai/docs/troubleshooting
Description: Fixes for common SpareTokens worker problems such as sandbox, provider and budget errors, and where to find answers to general questions about the project.

[Home](https://sparetokens.ai/) / [Docs](https://sparetokens.ai/docs) / Troubleshooting and FAQ

# Troubleshooting and FAQ

Fixes for common SpareTokens worker problems, and where to find answers to general questions.

Fixes for common problems with the worker. For general questions, see the [FAQ](https://sparetokens.ai/faq).

## Start with the self-check

Run `sparetokens doctor`. It is read-only and prints your OS, Python version, whether a sandbox is available, which providers it found, the provider-terms status, the config directory and whether the coordinator answers, followed by a short list of anything to look at. Paste its output into a bug report (it never contains a key). Add `--offline` to skip the network check.

## "no working OS sandbox on this machine"

Shell and solver tasks need an OS sandbox, and the worker never runs them without one. Run `sparetokens status`: the `sandbox:` line gives the exact reason and the fix. Literature tasks and other model-only tasks still work without a sandbox.
- **macOS:** `sandbox-exec` is built in. If it is missing, the system is unusual or damaged.
- **Linux, "bubblewrap is not installed":** `sudo apt install bubblewrap` (or your package manager's equivalent).
- **Linux, "does not allow unprivileged user namespaces":** common inside Docker and on some hardened hosts. Run the worker directly on the host or in a VM. If you control the container, relaxing its seccomp profile is your decision; the worker will not weaken its own sandbox to start.
- **Linux, "masks /proc":** a Docker container hides parts of `/proc`. The same advice applies; `--security-opt systempaths=unconfined` is the relevant container option.
- **Ubuntu 23.10 and later, "AppArmor restricts unprivileged user namespaces":** add an AppArmor profile for `/usr/bin/bwrap` that contains `userns,` and reload AppArmor. Setting `kernel.apparmor_restrict_unprivileged_userns=0` also works but relaxes a protection for the whole machine.
- **Native Windows:** there is no sandbox. Use WSL2 as described in [the quickstart](https://sparetokens.ai/docs/quickstart#windows).

To test bubblewrap by hand: `bwrap --ro-bind / / --dev /dev --unshare-all --die-with-parent true` should exit with status 0.

## Windows: "run SpareTokens inside WSL2"

You asked for something that needs a shell or a solver on native Windows. Install WSL2 with `wsl --install -d Ubuntu` in an administrator PowerShell, open Ubuntu, run `sudo apt update && sudo apt install -y bubblewrap python3-venv python3-pip`, and install SpareTokens there. Your Windows config is separate from the WSL2 one, so register or run setup again inside Ubuntu.

## Windows: odd characters or a console error

Older Windows consoles use a legacy code page. The worker replaces characters the console cannot show instead of stopping. For clean output, use Windows Terminal or set `PYTHONUTF8=1`.

## "cannot reach the coordinator"

The worker could not connect. Check the coordinator address with `sparetokens config show` and, if needed, pass `--coordinator URL` or set `SPARE_COORDINATOR`. [Planned] A public coordinator arrives with the beta.

## "the coordinator refused the request"
- **401:** your contributor token is missing or invalid. Register again, or check `worker.json` in your config folder (`sparetokens config path` shows it).
- **409 on register:** the handle is taken. The error includes a free suggestion.
- **429:** you hold the maximum of 3 open task leases, or you ran too many setup tests in an hour. Finish or release a task, or wait.
- **413:** a result was larger than 1,000,000 bytes.

## The worker will not start a task
- Run `sparetokens status`. It shows whether donation is paused and whether a source was paused by the circuit breaker.
- A source paused after three failed or rejected tasks stays paused for 24 hours. After you check the cause, run `sparetokens resume --breaker NAME` (or `sparetokens config reset-breaker NAME`).
- A source paused by reconciliation needs the same reset.
- Run `sparetokens config explain` to see what each rule would do right now, and why.
- A scheduled run respects quiet hours and "never on battery". A run you start yourself does not.
- If a run says a provider is not supported with a subscription login, that is intentional: use an API key or a local model. See [provider terms](https://sparetokens.ai/docs/providers#terms).

## No tasks match

The coordinator only hands out task types your tier can do. Literature tasks need web search, which only the Claude providers have, and compute tasks written by a model need tier 2. Check `sparetokens config models NAME` to see what each model unlocks. Try `--types run_solver re_verify` with `--provider none` for work that needs no model.

## A submission was blocked

Before submitting, the worker scans results for credential-shaped strings and for the values of your key variables. A match blocks the submission locally and releases the task. The log names only where it looked suspicious, never the text.

## The background service

Check it with `sparetokens service status` and read `sparetokens logs`. The service only runs sources whose rule is not manual. If the unit does not start, update to the latest worker, since earlier source checkouts could not be started as a module.
- **Linux, "systemd is not available":** under WSL2 add `[boot]` and `systemd=true` to `/etc/wsl.conf` and run `wsl --shutdown` from Windows. Without systemd you can run `sparetokens service-run` in a terminal or tmux.
- **Linux, it stops when I log out:** run `loginctl enable-linger $USER` once.
- **Windows, "Task Scheduler (schtasks)":** the install uses `schtasks`, which ships with Windows. If your administrator blocks it, run `sparetokens service-run` in a terminal instead. Remove the task with `sparetokens service uninstall`.

## Messages the worker prints, and what to do

Each heading is the start of a real message. The worker words these in plain language and always says what to do next.

### "Not donating: ..."

A rule is holding the run, and the sentence after the colon says which one and why. Run `sparetokens status` to see when it may change. The common ones:
- **"idle, power and temperature are not known yet, so it does not run":** an idle rule needs to read that the machine is idle, plugged in and cool, and it will not guess. Give it a minute and try `sparetokens status`. If it never becomes known, use a fixed rule for that source.
- **"the machine has been idle 2 minutes, it needs 10", followed by "Waiting for idle time":** working as designed. A source with an idle rule gives only while you are away, so the run stops without starting. To start right now anyway, add `--now`, for example `sparetokens run --provider local --source mac --now` (the plugged-in and temperature checks still apply). To change the wait, use `sparetokens give mac --idle --idle-minutes 5`.
- **"... is paused":** a source pauses after three failed or rejected tasks in a row, for 24 hours. After you check why, run `sparetokens config reset-breaker NAME`.
- **"DONATION PAUSED until ...":** you ran `sparetokens pause`. Run `sparetokens resume`.
- **"spend reconciliation failed":** the worker could not confirm what it spent against what the provider reports, so it stopped to be safe. Check the provider dashboard, then `sparetokens config reset-breaker NAME`.

### "worst case of one extra turn on this model is $2.70, but only $0.76 is available right now"

Every task must fit its worst-case cost inside every limit that applies. The message names what sets the small amount: for expiring credit it is the pace, because giving is spread evenly from the day you set it to the end date, so the first days have the smallest share. A large model's worst extra turn ($2.70 here) does not fit yet. This is the worker being careful, not a fault. The message ends with the exact command to run, which is a cheaper model:

```
sparetokens config set-models NAME --mode cheapest
```

That works for sources you created with `sparetokens give` as well as for ones in `config.json`. You can also wait for the share to grow, raise the balance, or use a fixed amount for your first run (`sparetokens give NAME --fixed 5`). `sparetokens config models NAME` shows what each model unlocks.

### "No giving rule for local (it is not a configured source), so only these limits apply"

Not an error. A run you start by hand with no `--source` is limited only by its own flags, such as `--max-tasks` and `--budget-usd`. Passing `--source NAME` applies that source's rule, including idle time and hours. For a source you have not set up, use `sparetokens give NAME --fixed 5`.

### "Nothing usable was found ..." in setup

Setup could not see an API key or a local model server. It still saves your other choices. Set the key in your environment (`export ANTHROPIC_API_KEY=...`) or start Ollama, LM Studio or an MLX server, then run `sparetokens setup` again. `sparetokens detect` lists what the worker can see. Claude and ChatGPT subscription logins are not supported on purpose.

### "Not registered", "No account token on this machine" and "handle already taken"
- **"Not registered. Run: sparetokens register --handle NAME":** this machine has no contributor token yet. Run the command, or run `sparetokens setup`.
- **"This computer is already registered as NAME":** `register` does not rename a machine that already has a worker. To change your public handle, run `sparetokens profile --handle NEWNAME`. To start a separate second worker here anyway, add `--replace`.
- **"rotate-token: the token was not changed":** this machine still holds the token it had. If the reason above it says 401, the coordinator no longer accepts that token, so run `sparetokens setup` or `sparetokens link CODE --replace` with a code from your dashboard.
- **"register error: 409: handle already taken; try NAME-1234":** a username must be unique ignoring case. Pick another, or use the suggestion. Usernames are 3 to 24 letters, digits, `_` or `-`.
- **"No account token on this machine":** agent tokens and account actions need the account token that `register` or `login` saves. If this machine is a second worker, use `sparetokens link` with a code from your dashboard.
- **"agent-token save: expected an agent token (it starts with spa_)":** the token is read from standard input, for example `pbpaste | sparetokens agent-token save`.

### "failed locally: local request failed ... 404 Not Found"

The local server answered, but it does not have the model name you passed. List models with `ollama list` and pass the exact name to `--model`. The task is released back to the queue, and nothing is submitted.

### Errors about rules and flags
- **"--budget-usd is required for provider ...":** that provider reports dollars, so a run needs a dollar cap. Add `--budget-usd 2`.
- **"--by must be a date like 2026-11-30":** expiring credit needs a real date. **"expiring credit needs the date it ends"** means `--by` is missing.
- **"percentage needs the budget it is a percentage of: add --of 50":** a percentage is of something. Give the dollars with `--of`.
- **"everything spare on an API key needs a ceiling":** add `--ceiling 20`, so "everything" is always bounded.
- **"something shaped like a secret at ...":** `rules.toml` only ever holds a key's name. Put the key in an environment variable or the keychain and use `key_ref = "env:NAME"`. The value is refused and never echoed back.
- **"NAME is set up in rules.toml ... config set-rule would change nothing":** a source created with `sparetokens give` keeps its rule in `rules.toml`, and that file wins. Change the rule with `sparetokens give NAME ...`. Model choices (`config set-models`) work for these sources.
- **"no source named NAME":** create it with `sparetokens give NAME --fixed 5` or `sparetokens config add-source`. See `sparetokens status` for the sources that exist.
- **"preview shows dollar budgets; this rule is in tokens":** use `sparetokens status` to see what a token rule will do now.

### "Refused task N ... Nothing was run" and "NOT VERIFIED"

The worker checks every task before it runs: the signature, the pack release, the template hash, the scope rules and the public log. On any failure it prints the reason, writes a local report, files a report with the coordinator, releases the task and stops. Nothing ran on your machine. This is the safety working. See [trust and verification](https://sparetokens.ai/docs/trust-and-verification), and run `sparetokens inspect TASK` to read a task yourself. If you think a task is wrong, run `sparetokens report TASK --reason broken`.

### Network and rate limit messages
- **"Rate limited; retrying in N s (attempt 1 of 5)":** the coordinator asked the worker to slow down. It retries by itself.
- **"network error (request not repeated, it may have been processed)":** a submission was cut off. The worker does not repeat it blindly. Check `sparetokens history` before running again.
- **"refusing coordinator URL ...: it must start with https://":** plain http is only allowed for localhost. Fix the URL in `--coordinator` or `SPARE_COORDINATOR`.
- **"No matching tasks available.":** nothing in the queue fits your model right now. See "No tasks match" above.

## More help
- Open a pre-filled issue with no secrets or logs: `sparetokens feedback bug --print-only`.
- Email [hello@sparetokens.ai](mailto:hello@sparetokens.ai).
- [FAQ](https://sparetokens.ai/faq), [limits and protections](https://sparetokens.ai/docs/limits-and-protections) and the [CLI reference](https://sparetokens.ai/docs/cli).

---
Part of SpareTokens (https://sparetokens.ai/). Full site index for agents: https://sparetokens.ai/llms.txt
