Troubleshooting

Start with toryo doctor. Its 23 checks cover host tools, configuration, services, database access and migrations, models, licensing, and client registrations. Each failure includes a repair hint.

On Windows, run these commands inside Ubuntu on WSL2, not in PowerShell. If toryo is missing inside Ubuntu, follow the Linux CLI installation instructions in that same terminal, then open a new Ubuntu terminal so its PATH changes take effect. Entering Ubuntu or installing Board alone does not establish a working Linux CLI. If you selected another WSL2 distribution, use its terminal instead.

toryo doctor
toryo doctor --json

toryo will not start#

Run toryo license status. A never-activated install needs a trial or key; an expired trial needs a key; a revoked seat needs an administrator. Activation requires the email address bound to the key. See Licensing.

A job is queued, or a sequence is blocked#

toryo foreman check
toryo dispatch health
toryo sequence health
toryo sequence status <runId>

A queued dispatch job usually means Dispatch is not consuming. A sequence may also be waiting for an approval, a live question, or a dependency run. Board shows those questions on the run. A failed dependency does not release its dependents automatically.

Environment repair required on an older run means an acceptance command could not run at all: a missing tool (exit 127) or a timeout. Fix the tool so your login shell finds it, then Retry capability. The run's acceptance job is an ordinary dispatch job, so toryo dispatch list shows whether it is queued or running. Local acceptance explains consent and evidence.

A Claude job crashed with harness_lingered#

Claude ended its session but its process did not exit, so toryo stopped it after 30 seconds instead of waiting out the job's timeout. toryo dispatch status <id> shows the session's end reason and whether the model had produced any output. Retry the job; if it keeps happening, report it through Feedback.

Search is weak, or Ollama is unavailable#

Ollama is optional. When unavailable it does not make Foreman red, but semantic search falls back to keyword matching and global memory writes queue for review.

ollama list
ollama pull nomic-embed-text
ollama pull llama3.1

The embedding and judging models do different jobs; install both. Explicitly starting unavailable Ollama through Foreman fails with its installation remedy. When TORYO_OLLAMA_MODE is external, run the equivalent list or API check against TORYO_OLLAMA_HOST and confirm that host is reachable. Foreman only health-checks an external endpoint; model installation and service lifecycle remain with its operator.

An external host that is not answering is reported unavailable, not failed, and setup saves it with a warning instead of refusing.

A service or the supervisor is stale#

Stale code is not failed health. It means a healthy process predates the installed code. Restart it after active work drains. If Board shows a queued restart badge, Foreman will apply that service's restart once it is safe.

A restart that cannot reach quiescence changes nothing and exits 75. Retry later, or use --force only if interrupting the active work is intentional. An update uses the same safety principle but refuses a busy machine with exit 68.

A draining Dispatch is not killed even with --force; wait for its jobs to finish.

The supervisor can be stale too. toryo foreman check then says it is running code that changed since it started, and Board shows a supervisor: stale code chip. It normally restarts itself within a few minutes. If the chip stays, run toryo supervisor restart on macOS (not stop then start), or systemctl --user restart toryo-foreman-watch.service on Linux. The restart can bounce the services it launched, so pick a quiet moment.

Foreman is green but reports schema drift#

toryo foreman check can be healthy while its schema field reports ok: false: an app database is missing migrations the installed binaries expect. Run the command in its fix, usually toryo <app> migrate, or toryo update when the migration files are themselves stale. The field refreshes about once a minute, or when you next run toryo foreman up.

If services read red while maintenance.held is true in toryo foreman check, Foreman is in the middle of starting or restarting the stack. Wait for it to finish before restarting anything yourself.

The database is unavailable or slow#

With Docker, confirm the daemon is running and port 5433 is reachable. With pglite there is no Docker daemon, but each database serializes queries through one backend session, so heavy parallel work can queue behind a long transaction. With TORYO_DATABASE_MODE=external, check TORYO_DATABASE_URL, network and TLS reachability, credentials, database-creation privileges, and permission to install vector. Foreman reports the connection health but does not restart an external server.

If pglite fails to start, the error names the databases that never came up and prints the server log from that attempt, and toryo stops the server it started before exiting. If the message says it could not stop it, run toryo pglite down before retrying. A first start can take a minute or two; it gives up only after 150 seconds without progress or 10 minutes in total.

Board cannot reach a command or tmux session#

A packaged Board resolves installed commands and its tmux launcher from the installed toryo root. If the installed binaries are missing, run toryo setup. Use the Foreman screen to distinguish a CLI-resolution problem from a down service. You can always attach directly with tmux attach -t <session>.

A pull request never opens#

The coding sequence requires an authenticated GitHub CLI:

gh auth status
gh auth login

Nothing here matches#

Capture toryo doctor --json and follow Feedback.