Error codes and exit codes

Read the message and Next: line before selecting a fix. Structured JSON includes code, details, and next when supplied by the error producer.

Exit codes

Code	Meaning
0	The requested operation succeeded.
1	An infrastructure or unexpected failure occurred.
2	A policy, state, or prerequisite refused the operation.
3	The command or input is invalid.

Operator codes

Code	Next action
CliVersionTooOld	Upgrade the CLI to the minimum version in project.toml.
MigrationPreflightFailed	Read the failed relocation step, correct the named record, and repeat the upgrade step.
WorkspaceNotRelocated	Follow the upgrade checklist for this checkout.
LegacyOperationUnavailable	Use the run or runs action named by the refusal.
ExecutionUnavailable	Start through e11 run or continue through e11 runs resume.
ToolkitNotPinned	Run e11 init, verify the pin, and commit project.toml.
PricingUnavailable	Restore a valid pricing.json, review rates, and commit the file.
SourceNotAtBaseline	Commit the required source bytes and plan from the matching checkout.
Generation1PreparationUnavailable	Use the compatible bridge release only within the coordinated cutover procedure.
CleanupStatusNotAdmitted	Finish or cancel the run before cleanup. Stopped runs do not admit cleanup.
CleanupHeadMismatch	Inspect the run branch and its recorded head before cleanup.
CleanupWorktreeDirty	Review and commit wanted worktree changes before cleanup.
CleanupRetentionConflict	Inspect the retained reference. Preserve the differing head.
AdministrationConfirmationRequired	Preview the administrative operation again and use the current confirmation token.
RunWorktreeRetired	Plan a new run from retained work. Cleanup ends resume and retry access to the released worktree.
SchemaUnsupported	Use a release compatible with the record or store.
LandingNotConfirmed	Follow the branch, file, or history correction in the landing refusal.
RunPlanInvalid	Read details.problems, correct source documents or profile selection, and plan again.

Error intake codes

e11 errors names every refusal with an E_ code and its remedy on the last line. The gate codes are the fails-first verdicts a bugfix profile's acceptance reports.

Code	Exit	Next action
E_GREEN_AT_BASE	2	The reproduction passes at the base, so it does not reproduce the bug: rewrite it from a real occurrence.
E_SIGNATURE_MISMATCH	2	The base fails with another error: fix the reproduction, or record the new signature with --red-only.
E_RED_AT_HEAD	2	The fix does not make the reproduction pass: the story is not done.
E_TESTS_FAILED	2	A test that did not fail at the staged base fails at HEAD, or the test command failed and printed no report to compare: fix what the listed tests show.
E_REPRO_DRIFT	2	The reproduction changed after it was recorded: run verify-repro --red-only again.
E_REPRO_ALTERED	2	The story edited the staged reproduction: restore it from the staging commit.
E_REPRO_WEAKENED	2	The story touched a guarded path or the runner's setup: revert that part of the change.
E_REPRO_SKIPPED	2	The reproduction did not run at HEAD: remove the skip or the filter that hides it.
E_STATE	2	The row is not in a state this action takes: follow the row's next step in the ledger.
E_STORY	2	The story draft lacks its # Story X.Y: title or acceptance criteria: fix the draft.
E_INVOKE_TOO_LONG	2	Shorten the invoke text to 4000 characters or fewer.
E_BASE_NOT_INITIALISED	2	Commit the e11 errors init output to the base branch.
E_BRANCH_EXISTS	2	Delete the stale branch, or use the one already there.
E_LEDGER	2	Correct the listed rows; nothing was appended or cut.
E_PORT_CONFLICT	2	The fix conflicts with the target branch: re-stage the cause on the current base, or port it by hand.
E_REDACTION	2	No longer raised: the scan of agent-written text warns and commits anyway.
E_TOOLCHAIN	2	A tool the night needs is missing or another version: fix the PATH in nightly.env, or start Docker. Schedule from an installed e11, never one npx runs from its cache.
E_PLATFORM	2	This machine has no launchd: add the printed crontab line, or use another scheduler.
E_ENV_EXPOSED	2	Others can read nightly.env, which holds tokens: chmod 600 it.
E_NO_PROJECT_ROOT	2	Run from the checkout, or pass --project-root.
E_NO_CONFIG	2	Run e11 errors init <project>, or fix .foundry/custom/e11-errors.toml.
E_NO_STAGING_COMMIT	2	Run the gate on a branch e11 errors stage made, or pass --fp for a hand run.
E_NO_LEDGER_ROW	2	Name a root cause the ledger holds, by slug or fingerprint.
E_PREPARE_REQUIRED	2	The fix changes files outside the runner's folder: give the runner a prepare command.
E_DIRTY_WORKTREE	2	Commit or remove uncommitted changes; the gate reverts the tree in place. For the night's own worktree, reset it: nothing but the night writes there.
E_RESTORE_PENDING	2	Check out the commit the journal names and run the gate again, or restore by hand.
E_NOT_AT_BASE	2	Check out the base tip, or name the base with --base.
E_TARGET_EXISTS	2	The reproduction's target path is taken: choose another target.
E_LOCKED	2	Wait for the other errors command to finish.
E_NOT_INITIALISED	2	Run e11 init, then e11 errors init <project>.
E_SOURCE_AUTH	2	Export the source token the config names, with read scope.
E_RUNNER	1	The runner crashed, timed out or could not start: read its output and run again.
E_SOURCE	1	The error source did not answer: run the pull again later.
E_RESTORE_FAILED	1	The journal is kept: run the gate again to restore, or restore by hand.
E_INTERNAL	1	Report the message with the command that produced it.
E_USAGE	3	Correct the command line.
E_RUNNER_UNKNOWN	3	Define the runner the reproduction names in [[workflow.runners]].

Internal store codes

Lease, fencing, journal, and integrity errors belong to Under the hood: the run store. Keep the recorded evidence when reporting a repeatable failure.

Error code contract