Errors

Every error code, its exit code and remedy.

Every failure Sponson reports carries a stable code. In --json output and MCP results it is error.code of the envelope ({ ok: false, command, error: { code, message, hint? } }) when the command could not run, and errorCode on a plan line or receipt line when one line failed. Branch on the code, never on the message.

When a command stops on an error, the code decides the exit code (the Exit column). When it runs to the end, line failures are reported in its output and the exit code is 1. hint (the CLI hint column) is the command-line remedy, appended to the message in text output and present as error.hint in JSON. ok in the envelope is true exactly when the exit code is 0.

Exit codes

Exit	Meaning
0	success, including an apply whose receipt is partial (waiting on an external event) or stale
1	failure: plan found a line in error or blocked, an apply’s receipt is failed, or the command stopped on a code with exit 1
2	the command was refused before it ran: the invocation, the plan, a reference, a parameter, the environment or the approval is wrong
3	the scope’s lock is held by another run, or this run lost it: wait and re-plan, never force

Codes

Code	Exit	Meaning	CLI hint
PLAN_PARSE	2	The plan file cannot be read or is not valid YAML.
PLAN_INVALID	2	The plan does not match the schema.
REF_UNKNOWN	2	A from: reference names a line that does not exist.
REF_CYCLE	2	References form a cycle.
REF_FILTERED	2	A reference crosses an environment filter.
REF_OUTPUT_UNKNOWN	2	A from: reference names an output the op does not declare.
CTX_NULL	2	A ${ctx.*} interpolation is unknown or null in this context.
ENV_UNKNOWN	2	The environment is not declared by the plan.
ENV_NOT_APPROVED	2	The run writes to production and nobody approved it: no --approved-by, SPONSON_APPROVED_BY or MCP approved_by.	Pass —approved-by <who> or set SPONSON_APPROVED_BY from an approval workflow.
SECRET_LITERAL	2	A parameter that looks like a secret is written as a literal.
SECRET_UNRESOLVED	1	A secret source could not resolve a reference.
ADAPTER_UNKNOWN	2	No adapter of that name is registered.
OP_UNKNOWN	2	The adapter has no op of that name.
PARAM_INVALID	2	An adapter rejected a parameter.
USAGE	2	The command line is wrong.
MANUAL_STEP_PENDING	2	A manual step (manual.step) is not done yet, or its undo on destroy: a person must do it, by its instructions, and then confirm it; its line and the lines that depend on it wait. Nothing else is held back.	A person does the step as instructed, then runs apply again with —confirm <line> (with —approved-by <who>, or as the git user). Agents never confirm on their own.
DRIFT_CHANGED	1	A resource was changed or replaced outside Sponson; the line is refused unless the run reconciles.	Keep that change by updating the plan to match, or re-run with —reconcile to overwrite it.
LOCK_HELD	3	Another run holds the scope’s lock.	Wait for it, or pass —wait.
LOCK_LOST	3	The run lost the scope’s lock to another run and stopped.
RECEIPT_CORRUPT	1	The receipt cannot be parsed.
RECEIPT_VERSION	1	The receipt was written by a newer Sponson.
STORE_PERMISSION	1	The receipt store cannot be read or written.
STORE_CONTENDED	1	The receipt store stayed contended past the retry budget.
STORE_REJECTED	1	The receipt store kept rejecting the receipt; a fallback copy was kept.
WAIT_TIMEOUT	1	An external event did not happen within the wait timeout.
OWNED_BY_OTHER_SCOPE	1	Another scope in this environment manages the resource.
OUTPUT_UNAVAILABLE	1	A line needs an output its provider reveals only when the resource is created (a password), that resource was created in an earlier run, and the line cannot be shown to hold the value; nothing is re-created to get it back unless asked.	Pass —recreate <line> to create the producing line’s resource again (its new value reaches every dependent in that run), or keep the value in a secret manager and reference it with { secret: … }.
INTERNAL	1	An unexpected error.
PROVIDER_TRANSIENT	1	The provider failed transiently (after retries).
PROVIDER_CONFLICT	1	The provider reported a conflict.
PROVIDER_NOT_FOUND	1	The provider reported that something does not exist.
PROVIDER_AUTH	1	Credentials are missing or rejected.
PROVIDER_INVALID	1	The provider rejected the request as invalid.
PROVIDER_TIMEOUT	1	The provider did not answer in time.
PROVIDER_RESPONSE	1	The provider answered with an unexpected shape.
DEPENDENCY_BLOCKED	1	A line this one depends on failed or is blocked.
EXTERNAL_FAILED	1	The external event a line waits for failed.
INTERRUPTED	1	The run did not finish (checkpoint written before a create).
INTENT_UNRESOLVED	1	An interrupted create cannot be located; check the provider by hand.
ROLLBACK_FAILED	1	Rolling back what the run created failed; resources were left behind.
DESTROY_FAILED	1	Destroying a resource failed.
STALE	1	The commit is older than the last applied one; nothing was changed.

Warnings

Warning codes never fail a run and have no exit code.

Code	Meaning
YAML_ANCHOR	The plan uses YAML anchors/aliases; allowed, but hard to read.

Adding a code

Add it to ERROR_CODES in packages/core/src/errors.ts with its exit code, a doc line and, when the CLI has a remedy, a cliHint; then run pnpm docs:gen and commit the regenerated docs/errors.md.