forgev0.19
Docs pages

When something goes wrong

Every task's records live in its run folder, so you can always read what a model actually said. Start with the status.

Task statuses

StatusWhat it means, and what to do
FAILA blocking finding. Retry with the findings, maybe on a stronger model.
UNKNOWNNo verdict. A retry asks the reviewer again on the same work; no dwarf runs, no attempt is spent.
INVALIDATEDThe reviewer edited a tracked file in its copy, so its verdict counts for nothing. Retry reviews the unchanged work.
INFRAA provider problem: rate limit, quota, sign-in, network, or a CLI that cancelled its own session (grok does at a command it can't approve headless). No attempt spent. If it says "needs you", log in or add credits; otherwise run the same command again, or use --infra-retries.
TIMEOUTA model ran past the limit. Raise --timeout, or retry; partial work is in the worktree.
CONFLICTReview passed but the merge conflicted, usually a file the task didn't declare. The scope-drift list names it.
ERRORA worktree or dispatch failed. Read tasks/<id>/dwarf.out or qa.out.
NEEDS_DECISIONThe retry policy stopped, or every blocking finding needs a file another task owns. tasks/<id>/decision.md lists the choices. Decide with forge control retry --decide; see Steering.
NEEDS_INPUTThe task asked you a question. Answer it with retry --answer, or in forge-ui's task panel.
STALEIts prompt changed while the attempt ran. Not reviewed, no attempt spent; the dwarf runs again with the new text.

Surprising results

What happenedWhy, and the fix
Merged although the reviewer said FAILEvery finding was milder than the threshold, so it passed with known issues, listed in known_issues.md.
Failed although the reviewer said PASSIt listed a confirmed finding at the threshold or worse. forge goes by the findings.
The dwarf produced no changesUsually a goal it couldn't settle alone. Make it more specific, or turn on brief mode.
Several tasks produced nothingThe split made tasks that can't stand alone. Use a coarser --decompose-level.
Every wave has one taskMost tasks share files. Split the goal differently.
Pieces don't fit togetherThe shared interface was never agreed. Plan first, or use --planner.
FLAKY with a passing verificationThe check failed once and passed on rerun. Read verification.log; it can be a real bug.
Reviews say their tests couldn't runThe reviewer's sandbox lacked something. The run summary lists those reviews; check the dependency or the verify command.

Installation

ProblemFix
/forge missing in a CLIRun forge install again and restart the session.
Antigravity runs an old versionIt copies forge's files. Run forge install after every update.
Antigravity dwarf ends with an empty diffIt tried a shell command without --yolo-dwarf; one refusal ends its run.
OpenCode shows forge twiceIt finds forge in ~/.claude/ on its own. Remove the extra copy.

Recovering

  • An interrupted run isn't lost: run the same run again. Merged tasks are skipped.
  • A failed task is cheap to redo: retry reuses its worktree and findings.
  • "Already exists" on retry means a worktree folder was deleted by hand. Run the command again rather than deleting the branch.
  • A wrong memory fact keeps coming back: forge memory forget REPO category:key.
  • The session that started a run is gone: forge handoff in any CLI, then forge handoff resume.
  • A locked plan tells you which command holds it. On a live run, use forge control.

Full reference Every flag and edge case: docs/troubleshooting.md