Troubleshooting

When a cycle doesn’t do what you expect, you have two places to look: the CLI exit code / message, and the console root-cause drill-down. This page maps the common symptoms to causes and fixes.

First stop: the cycle drill-down

Every cycle has a root-cause page in the console:

https://thothato.io/dashboard/cycles/<cycleId>

The CLI prints this link whenever a cycle fails or the live stream drops. The page shows:

Root-cause banner — a plain-English summary of what happened and a suggested fix; on failure, expand View error + stack for the captured error.
Phase timeline — the six phases (Specify → Architect → Develop → Test → Synthesize → Govern) with status. Click any phase to inspect its output; the failing phase is highlighted.
Verdict — the six principle scores, intent-alignment (vs the 0.70 approval threshold), and the signed-verdict record — or, if the cycle failed before signing, the reason.

Open this first — it usually tells you exactly which phase failed and why.

CLI exit codes

Code	Meaning	What to do
`0`	Success — deliverable written	—
`1`	User error — bad credentials, quota exceeded, bad goal, or verdict not approved	Read the message; fix the input or upgrade your plan
`2`	Server error — a 5xx or an unparseable response	Retry; if it persists, the dashboard cycle page shows the cycle state
`3`	Network error — the request failed or the live stream couldn’t reconnect	The cycle is usually still running server-side — open the dashboard cycle page for its status and result

A dropped live stream (exit 3) does not mean the cycle failed — execution continues on the server. Re-open the cycle page to see the outcome.

Common causes

”Cycle paused” / nothing happens after Specify

Your goal was too ambiguous (ambiguity score above the 0.70 gate), so the cycle paused for clarification instead of guessing. Fix: resubmit a more specific goal — name the language, the inputs, and what “done” looks like.

✅ Write a Python function fib(n) returning the nth Fibonacci number, with pytest tests for n=0,1,10 ⚠️ build a fibonacci thing with story points

”Verdict: rejected”

The cycle ran to completion and produced a signed verdict, but the Judge rejected it — usually because the deliverable didn’t cover the specified intents (intent-alignment below 0.70). Fix: open the drill-down; the verdict panel shows the principle scores and intent-alignment so you can see what fell short, then refine the goal.

`401` / `403` — auth

Your API key is missing, wrong, or lacks the scope. Fix:

thoth config show          # confirm a key is set
thoth config set-api-key thk_…

`Bad goal: Invalid enum value … provider`

Your configured LLM provider name isn’t recognized. Use one of: anthropic, openai, gemini, vertex, ollama, lmstudio, custom.

thoth config set-provider anthropic

`429` — quota

You hit the signed-verdict cap (Free = 50/month). Unsigned cycles are unlimited. Fix: upgrade to Pro for unlimited signed verdicts, or wait for the next billing period.

Useful commands

thoth config show                 # current API key (masked), provider, endpoint
thoth --version                   # CLI version
thoth "…clear, specific goal…"    # dispatch a remote cycle

If a cycle’s outcome is unclear from the CLI, the dashboard cycle page is always authoritative.

Still stuck?

Email support@thothato.io with the cycle ID (shown when you dispatch, and in the dashboard URL). Include the goal text and what you expected — the cycle ID lets us pull the full root-cause trail.