Find your message

When something goes wrong, match the text Kusaw printed or the reason code it recorded. Entries are grouped by where you see them. Each one quotes the message as the factory prints it, with placeholders where the factory fills values.

The factory has to be serving for the queue to move. If a command says serve is not running, start it with kusaw serve first.

Questions that are not a specific failure are in the FAQ.

InstallingCopy Anchor Link

Claude Code was not foundCopy Anchor Link

You see: Claude Code was not found ("<command>"). Install it or set claude.command in kusaw.yaml. What it means: the step tried to start the agent CLI and it was not on PATH (or the configured command does not exist). What to do:

1. Install the Claude Code you already use and confirm it is on PATH.
2. If the binary is not named claude, set claude.command in kusaw.yaml.
3. If the CLI is installed but not signed in, sign in with that CLI's own docs; Kusaw does not ask for credentials. Reference: Install, kusaw.yaml

Starting the factoryCopy Anchor Link

kusaw serve is not runningCopy Anchor Link

You see: Request <id> is queued. kusaw serve is not running, so it will be handled when it starts. What it means: the command was accepted and written to the queue. Nothing runs until serve is up. What to do:

1. Start the factory with kusaw serve.
2. Open the Dashboard with kusaw ui --open.
3. Check kusaw status. A down monitor prints Monitor: down (no heartbeat for <duration>). Reference: Install

Adding a taskCopy Anchor Link

kusaw.yaml is invalidCopy Anchor Link

You see: kusaw.yaml is invalid: <message> (line <n>). or a summary that starts kusaw.yaml is invalid: What it means: kusaw validate (or kusaw add) rejected the config. The line number is in the file it read. What to do:

1. Run kusaw validate and fix the first error.
2. Check the key on that line against the config reference.
3. For a missing version, the factory also prints kusaw.yaml version <version> is not supported. This factory reads version 2. Reference: kusaw.yaml

A run that failedCopy Anchor Link

Step "review" timed outCopy Anchor Link

You see: Step "<id>" timed out after <duration>, or the reason code timeout on the step. What it means: the step ran longer than its limit and was stopped. What to do:

1. Check the step's log for where it stopped (<data_dir>/runs/<run>/attempts/ then stderr.log).
2. Raise steps.<id>.timeout if the work is just slow. Reference: Reason codes

crashedCopy Anchor Link

You see: the reason code crashed on the step, or on stderr [serve] factory "<name>" crashed: <message>. Restarting in <n> s. What it means: the step process exited without a valid result, or a served factory panicked and the supervisor is restarting it. What to do:

1. Open the attempt's stderr.log and stdout.jsonl under <data_dir>/runs/<run>/attempts/.
2. If a custom step crashed, fix the process and run kusaw validate so the handshake still passes.
3. If serve itself crashed, read the serve log, then start kusaw serve again. Reference: Reason codes

rate_limitedCopy Anchor Link

You see: Claude Code hit a rate limit:, or the reason code rate_limited. What it means: the user's configured Claude Code refused the call because of a usage or rate limit. Kusaw retries once after 60 seconds (or the provider's reported wait, up to 15 minutes), then fails. Requeue is the next try. What to do:

1. Wait and let the step retry, or requeue the run later.
2. Check the plan and usage on the Claude Code account you configured. Kusaw does not manage that account.
3. Shorten the task if the work is larger than that plan allows. Reference: Reason codes

Verification command failedCopy Anchor Link

You see: Verification command <n> failed: <message>, or Verification command <n> failed in "<label>": <message>, or the reason code verification_failed. What it means: a command from the spec's ## Verification section exited non-zero (or timed out: (timed out after <duration>)). What to do:

1. Run that command yourself in the worktree and read its output.
2. Fix the change, or fix the verification command if the command is wrong.
3. If the spec has no commands, the factory prints The spec has no Verification commands. Reference: Reason codes, Write a good task

A run that needs attentionCopy Anchor Link

needs_attention after the loop limitCopy Anchor Link

You see: Needs attention: in kusaw status, the run status needs_attention, and the reason loop_exhausted. What it means: the loop used every iteration (max_iterations) without passing. The run is finished and waiting for you; it will not retry on its own. What to do:

1. Read the last findings on the run page.
2. Requeue with a note (kusaw requeue <run> --note "..."), dismiss it, or take it over and finish by hand.
3. Raise the loop's max_iterations only if more tries would actually help. Reference: Reason codes, Rerun, requeue, resume or steer

Steps and providersCopy Anchor Link

The agent CLI entries above (Claude Code was not found, rate_limited) are the provider failures users hit first. Messages printed by Claude Code itself are in that CLI's own docs.

Custom stepsCopy Anchor Link

protocol_error from a custom stepCopy Anchor Link

You see: the reason code protocol_error, or protocol error, or Step "<id>" speaks protocol <versions>; this factory needs protocol 2. What it means: the step did not speak protocol 2: missing or extra result line, invalid JSON, or a handshake that does not offer version 2. What to do:

1. Run kusaw validate so the handshake is checked before a run.
2. Confirm the program writes one handshake line and one result line, as in Write your first step.
3. Check stdout.jsonl for the line the adapter rejected. Reference: Reason codes, Step protocol

Custom step handshake failedCopy Anchor Link

You see: step "<id>" handshake failed: <message>, no handshake line within 5 s, or invalid handshake JSON. What it means: kusaw validate (or the start of a run) asked the step for a handshake and did not get a valid protocol 2 reply in time. What to do:

1. Run the command from steps.<id>.command yourself with the handshake env the protocol reference describes.
2. Fix the program so it prints one JSON handshake line and exits 0.
3. If the handshake's interactive flag does not match kusaw.yaml, the factory prints step "<id>" says interactive: <flag> in its handshake but kusaw.yaml says <flag>. Reference: Custom steps, Step protocol

The DashboardCopy Anchor Link

A gate is waitingCopy Anchor Link

You see: Waiting for you: in kusaw status, a line <run> <task> gate "<gate>" since <time>, and the run status waiting_for_human. What it means: the pipeline reached a gate. Delivery waits until you approve or reject. What to do:

1. Open the run in the Dashboard, or run kusaw status.
2. Read the summary, diff, verification output, and review findings.
3. Approve with kusaw approve <run> (or the Dashboard button), or reject with a note. Approval delivers a local commit; Kusaw never merges or pushes. Reference: Review and approve a run, Read the Dashboard

A run stays queued while the queue is pausedCopy Anchor Link

You see: Queue: paused (or Queue: paused (<cause>)) and Queued (<n>): with the run still queued. The first queued run is marked [next] but does not start. What it means: pause is on, so the factory will not take the head of the queue. Serve can be up and the run still waits. What to do:

1. Confirm pause with kusaw status.
2. Resume with kusaw resume. If the queue is not paused, that command prints Queue is not paused.
3. If serve is also down, start kusaw serve as in kusaw serve is not running. Reference: Read the Dashboard, Reason codes