Troubleshooting
Start with toryo doctor. It checks every dependency, every service, the
database, the license, and the brain registration, and prints the exact command
for anything it finds. Most of what follows is a doctor check with more context.
toryo doctor
toryo doctor --json # the same, for pasting into a bug report
toryo will not start#
The license gate holds the services down rather than killing them, so the symptom is that nothing comes up rather than a crash.
toryo license status
| What it says | What to do |
|---|---|
| never activated | toryo license trial --email you@example.com, or activate a key |
| trial ended | Enter a license key. The clock cannot be restarted. |
| gated | The seat was revoked, or the cached proof is unreadable. Re-run toryo license activate. |
| over seat | Your team is past its seat count. Your administrator adds one. |
If activation itself fails, check that the email matches the one the key was issued to. The key alone is not the credential, and a mismatch is reported differently from a mistyped key so you can tell which of the two is wrong.
A job sits in queued and never runs#
The dispatch daemon is not consuming. Check the supervisor first:
toryo foreman check
toryo dispatch health
On macOS the supervisor is a launchd agent. If foreman check reports it is not
running, toryo setup reinstalls it; the command is idempotent and safe to
re-run against a working install.
A sequence run stays blocked or queued#
A run waits on a gate, on another run, or on the sequence daemon.
toryo sequence status <runId>
toryo sequence health
A run that is blocked on a gate is waiting for you. A run blocked on
--depends-on waits for the other run to succeed, and stays blocked forever if
that one failed.
Search returns nothing useful#
Semantic search needs Ollama and both models. Without them everything falls back to keyword matching, which fails on a paraphrase.
ollama list # both models present?
ollama pull nomic-embed-text # embeddings
ollama pull llama3.1 # the judge
An install with only the embedding model embeds correctly and fails every judgement, so global memory writes queue instead of landing.
The database will not come up#
On Docker, the daemon has to be running before toryo can reach Postgres on port 5433. That port is deliberate, to avoid colliding with a Postgres you already run on 5432.
On pglite, there is no daemon to start, but queries serialize through one backend session per database. A run that feels stalled under heavy parallelism is usually queueing rather than hung.
The board cannot talk to the CLI#
A packaged app prefers ~/.toryo/bin/<app>. If those binaries are missing, run
toryo setup to reinstall them. You can force either behaviour:
TORYO_USE_BINARIES=1 open -a Toryo # prefer installed binaries
TORYO_USE_BINARIES=0 open -a Toryo # prefer a source checkout
Note that Open in tmux is broken in a packaged app. Attach yourself with
tmux attach -t <session> until that is fixed. See
Known limitations.
A pull request never opens#
The coding sequence opens a PR as part of a normal run, so it fails partway through if the GitHub CLI is not signed in:
gh auth status
gh auth login
Nothing here matches#
Send it to us. Feedback says what to attach so the first reply is useful rather than a request for more detail.