Troubleshooting

The messages below are the ones people actually run into. Each has what it means and what to do.

Dynamic workflows

I asked for dynamic workflows but no sub-agents started

Slo only starts sub-agents when you ask for them explicitly. Use the words "dynamic workflows", or "in parallel", "spawn sub-agents" or "at the same time". A request like "do this properly" won't do it.

If you asked and it still didn't happen, check for the next message.

`pool sealed by abort; no new sub-agents will be spawned`

Stopping a task with Ctrl+C or /abort also stops the session from starting any more sub-agents, so an abort can't be undone by accident. Start a fresh session with /new (or restart slo) and ask again.

`sub-agent produced no output for 7200s; treated as hung`

A sub-agent went two hours without printing anything, so Slo stopped it. Usually it was waiting on something that never finished, such as a command waiting for input or a server that never started. Check its stderr in slo visualize (select it, press d).

If the work really is that slow and silent, raise SLO_SUBAGENT_INACTIVITY_TIMEOUT_SECONDS.

`main agent stream produced no events for Ns; treated as hung`

Same idea, for the main agent or orchestrator. The default is 3 hours. If you've lowered SLO_STREAM_INACTIVITY_TIMEOUT_SECONDS, put it back to 10800.

A sub-agent failed and I don't know why

Read the orchestrator's summary. Each failed sub-agent's answer, or the tail of its stderr, is in there.
In slo visualize, select the sub-agent and press d for its diagnostics.
Look in ~/.slo/sessions/history/<orchestrator-session>/children/<sub-agent>/ at stderr.jsonl and status.json.

Or ask Slo to do it: "Why did the sub-agents in the last workflow fail? Read their stderr and status files."

A sub-agent says it has no credentials, but my API key is set

Sub-agents don't inherit API keys or tokens from your environment, for safety. Sign in once with /auth so the credentials are saved, and sub-agents will use those.

A background workflow shows as `stalled`

Its orchestrator process died without finishing. Either bring it back:

/workflows resume <id>

or acknowledge it and move on:

/workflows dismiss <id>

`workflow cap reached (2 live, max 2)`

A session can run two background workflows at once. Wait for one to finish, stop one with /workflows abort <id>, or raise SLO_MAX_DETACHED_WORKFLOWS.

`no evidence-backed correction for <id>`

A workflow was stopped with kill or pkill, so its records disagree about how it ended. Start a new session with /new. In future, stop workflows with /workflows abort <id>.

"Are we done?" gets a vague answer

Ask Slo to check against the source of truth instead of its memory: "Is task 12.b complete against specifications/12-refunds/? List done, partial and missing items with file paths." See Supervise a dynamic workflow.

Models and rate limits

`Rate limited by <model>; retrying in Ns`

The provider asked Slo to slow down. It waits and retries automatically. Nothing to do unless it keeps happening, in which case set up a model pool so the work moves to another model instead of waiting.

`<model> rate limit reached; retry budget exhausted`

The retries ran out. Wait a minute and ask Slo to continue, or add a second model with SLO_MODEL_POOL.

`All models in pool are in cooldown`

Every model in your pool hit a limit at once. Wait for the cooldowns, which are 60 seconds for rate limits and 5 minutes for credit problems by default, or add another model to the pool.

`/model` says `requires /auth`

You're not signed in to that model's provider. Run /auth, pick the provider, and try again.

I switched with `/model` and my pool stopped working

Switching models turns a pooled session into a single-model session. Restart slo to get the pool back.

An OpenRouter model is missing from `/model`

Slo only lists models OpenRouter says your key can use, and it doesn't re-check every time you open the picker. Run /model refresh. If the model is still missing, check on openrouter.ai that your key has access to it.

`model_catalog_cache_load_failed`

Most people never see this. It affects machines that ran an early development build of the OpenRouter support, before v0.21.

What you see. An older Slo (v0.20 or earlier) prints model_catalog_cache_load_failed with a traceback, often from a command that has nothing to do with models, such as slo --version or slo visualize. The details list missing fields (generated_at, entries, aliases, templates) and say provider_slices is not permitted.

Why. That early build wrote the new catalog format into the old file name, model_catalog_cache.json. Released Slo keeps the new format in its own file, model_catalog_cache.v2.json, and leaves the old one alone. Older versions still read the old name and reject what they find there. Slo catches the error, so your sessions and history are not affected, but the message comes back on every launch until the file is moved.

What to do. Stop using the development build, quit every running Slo, then check the old file:

grep -l '"schema_version": *"2"' ~/.slo/global/model_catalog_cache.json

If that prints the file name, move it aside:

mv ~/.slo/global/model_catalog_cache.json ~/.slo/global/model_catalog_cache.json.bak

Current Slo doesn't read that file. If the command prints nothing, leave the file alone: it's a valid cache in the old format.

If Slo also warns that your OpenRouter key is in the wrong file, remove it from authentication.json and add it again with /auth. Slo saves it to authentication.additional-providers.json. Use your SLO_HOME folder in place of ~/.slo if you've moved it.

Sessions

`unknown session reference`

No session has that id or name. Session names are only saved when history is on, which it always is in the TUI and only with --enable-history for slo run.

`ambiguous session reference`

More than one session matches. Resume with the full session id instead.

`cannot start a new session while a prompt is in flight`

/new and /compact wait for the current task. Run /abort first, or let it finish.

Slo seems to have forgotten the start of a long session

Long sessions are summarised automatically once they fill about 70% of the model's context. Details from early on can get compressed. Put anything that must survive into SLO.md or RESEARCH.md (see Give Slo a memory), or start a fresh session for a new topic.

The callback listener waits 60 seconds. On a remote machine, use OpenAI's device-code option, or paste the response by hand when Slo offers. To give yourself longer, raise SLO_OAUTH_TIMEOUT_SECONDS.