Errors & recovery

Errors are structured data an agent can act on. Never a stack trace, never silent, and every failure names a fix.

The error-code enum

The eight bridge-envelope codes (the ErrorCode enum in mcp_server/models/envelope.py — what the addon can emit):

Code	Meaning	Typical cause
PRECONDITION_FAILED	a required state is missing	no scene open, missing confirm, toolset version gate
RESOURCE_NOT_FOUND	a node/scene/script/resource path does not exist	typo'd path; use get_scene_tree / get_filesystem_tree first
VALIDATION_ERROR	parameters are malformed or refused	unknown ProjectSettings key, dimension mismatch, bad enum value
BRIDGE_DISCONNECTED	Godot is not reachable	editor closed / addon disabled / bridge URL wrong
TIMEOUT	the request outlived its timeout (may carry a readiness reason)	a capture that never landed; a stalled editor
INTERNAL_ERROR	a handler failed without producing a response	a GDScript error inside the addon (see the editor's Output panel)
APPROVAL_DENIED	the human declined an approval	n/a — retry with different intent
PEER_REPLACED	a server notice to the editor that a second editor took over the bridge (not a tool failure)	two editors pointed at one server; the replaced dock shows purple and stops reconnecting (#593)

Two server-side codes appear in ToolError text but never cross the bridge (the server rejects before dispatching, or bounds the payload locally):

Code	Meaning	Typical cause
PARAM_ERROR	a path parameter rejected server-side before the bridge call	a script/resource path that isn't res://-contained (res://../…, res:///abs)
OUTPUT_LIMIT	a result payload would exceed the 25k character cap	an oversized snapshot_subtree — narrow with max_depth

The recovery table

Error / symptom	Fix
unknown tool	the toolset isn't enabled → godot_enable_toolset(...); or you mixed a server-side tool with an editor tool
[required=active_scene]	godot_scene_edit_open_scene(path) or create_scene
[required=confirm]	destructive call → dry_run first, then confirm=True
[required=bridge_connected]	open Godot with the addon; check the status dock
[required=runtime_probe]	register MCPRuntimeProbe as an autoload
[required=game_not_breaked]	the game is frozen at a debugger break → godot_debugger_continue_execution
[required=godot_version]	the toolset needs Godot 4.4+ → upgrade the editor
VALIDATION_ERROR: Unknown ProjectSettings key … did you mean …	use the suggested key (e.g. application/run/main_scene, not application/config/main_scene)
persisted: false + hint	act on the hint (e.g. godot_scene_edit_set_editable_children) or retarget
rescan_pending: true	re-run the parse check once; the editor's scan hadn't flushed
NON-ZERO EXIT on a real crash	read errors[] from the run; fix and re-verify
RUN TIMED OUT	if the game never self-quits, pass expected_timeout=true to godot_debug_workflow

Design rules

1. Failures are data. {ok: false, error, hint} crosses the envelope; the server shapes the same structure into a ToolError for the client.
2. hint is for recovery — written for an agent with no human in the loop. A hint that restates the code is a bug.
3. Preconditions carry required — the machine-checkable name of what to satisfy.
4. No partial success. A result never reads as success when the effect half-failed: aborted_at, undoable, persisted, and rescan_pending exist so the agent never has to guess.
5. No invented codes. Clients match on the enum; a new code is an additive contract change.

The envelope-level rules are pinned by contract tests against a fake addon peer — a shape change without a contract-test update is a drift bug.