SpareTokens

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

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.

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, 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

Edit this page on GitHub: available when the repository opens.