Home / 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.
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-execis 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=unconfinedis the relevant container option. - Ubuntu 23.10 and later, "AppArmor restricts unprivileged user namespaces": add an AppArmor profile for
/usr/bin/bwrapthat containsuserns,and reload AppArmor. Settingkernel.apparmor_restrict_unprivileged_userns=0also works but relaxes a protection for the whole machine. - Native Windows: there is no sandbox. Use WSL2 as described in the quickstart.
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.jsonin your config folder (sparetokens config pathshows 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(orsparetokens config reset-breaker NAME). - A source paused by reconciliation needs the same reset.
- Run
sparetokens config explainto 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.
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]andsystemd=trueto/etc/wsl.confand runwsl --shutdownfrom Windows. Without systemd you can runsparetokens service-runin a terminal or tmux. - Linux, it stops when I log out: run
loginctl enable-linger $USERonce. - Windows, "Task Scheduler (schtasks)": the install uses
schtasks, which ships with Windows. If your administrator blocks it, runsparetokens service-runin a terminal instead. Remove the task withsparetokens 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 examplesparetokens run --provider local --source mac --now(the plugged-in and temperature checks still apply). To change the wait, usesparetokens 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. Runsparetokens 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":
registerdoes not rename a machine that already has a worker. To change your public handle, runsparetokens 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 setuporsparetokens link CODE --replacewith 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
registerorloginsaves. If this machine is a second worker, usesparetokens linkwith 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
--byis 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.tomlonly ever holds a key's name. Put the key in an environment variable or the keychain and usekey_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 givekeeps its rule inrules.toml, and that file wins. Change the rule withsparetokens give NAME .... Model choices (config set-models) work for these sources. - "no source named NAME": create it with
sparetokens give NAME --fixed 5orsparetokens config add-source. Seesparetokens statusfor the sources that exist. - "preview shows dollar budgets; this rule is in tokens": use
sparetokens statusto 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, 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 historybefore running again. - "refusing coordinator URL ...: it must start with https://": plain http is only allowed for localhost. Fix the URL in
--coordinatororSPARE_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.
- FAQ, limits and protections and the CLI reference.
Edit this page on GitHub: available when the repository opens.