Error Code Playbook (v3 Contract)
All tool/resource failures now use one JSON envelope shape:
{
"code": "invalid_command",
"message": "...",
"details": {},
"descriptor": {
"category": "validation",
"retryable": false,
"exitCode": 64,
"httpLikeStatus": 400
},
"recovery": {
"summary": "...",
"fix_command": "..."
}
}
Use this table as the source-of-truth contract for emitted code values.
| Code | Source area | Meaning | Retryable | Exit code | Recovery command |
|---|---|---|---|---|---|
unexpected_executor_error | core executor | Unhandled execution failure. | false | 70 | flutter_mcp_cli doctor --json |
connect_failed | connection layer | VM target connection failed. | true | 67 | flutter_mcp_cli exec --name get_vm --args '{"connection":{"uri":"ws://127.0.0.1:8181/<token>/ws"}}' |
vm_not_connected | VM command guard | VM-dependent command called without connection. | true | 68 | flutter_mcp_cli exec --name status --args '{}' |
connection_selection_required | connection selection | Multiple targets exist; explicit target required. | true | 64 | flutter_mcp_cli exec --name discover_debug_apps --args '{}' |
discover_debug_apps_failed | discovery | Target discovery failed. | true | 69 | flutter_mcp_cli doctor --json |
get_vm_failed | VM tools | get_vm execution failed. | true | 68 | flutter_mcp_cli doctor --json |
get_extension_rpcs_failed | VM tools | get_extension_rpcs execution failed. | true | 68 | flutter_mcp_cli doctor --json |
hot_reload_failed | VM tools | Hot reload execution failed. | true | 69 | flutter_mcp_cli doctor --json |
hot_restart_failed | VM tools | Hot restart execution failed. | true | 69 | flutter_mcp_cli doctor --json |
get_active_ports_failed | discovery | Active debug port lookup failed. | true | 69 | flutter_mcp_cli doctor --json |
get_app_errors_failed | toolkit bridge | App error retrieval failed. | true | 69 | flutter_mcp_cli doctor --json |
get_screenshots_failed | toolkit bridge | Screenshot retrieval failed. | true | 69 | flutter_mcp_cli doctor --json |
get_view_details_failed | toolkit bridge | View details retrieval failed. | true | 69 | flutter_mcp_cli doctor --json |
debug_dump_failed | VM dump tools | Dump command failed. | true | 69 | flutter_mcp_cli doctor --json |
dynamic_registry_disabled | dynamic registry | Dynamic registry is disabled in runtime config. | false | 78 | flutter_mcp_cli --dynamics exec --name status --args '{}' |
dynamic_registry_list_failed | dynamic registry | Dynamic tool/resource listing failed. | true | 69 | flutter_mcp_cli doctor --json |
missing_tool_name | dynamic registry | Dynamic tool name was required but missing. | false | 64 | flutter_mcp_cli doctor --json |
dynamic_tool_failed | dynamic registry | Dynamic tool invocation failed. | true | 69 | flutter_mcp_cli doctor --json |
missing_resource_uri | dynamic registry | Dynamic resource URI was required but missing. | false | 64 | flutter_mcp_cli doctor --json |
dynamic_resource_failed | dynamic registry | Dynamic resource read failed. | true | 69 | flutter_mcp_cli doctor --json |
session_manager_not_configured | session layer | Session command called without session manager wiring. | false | 70 | flutter_mcp_cli doctor --json |
session_not_found | session layer | Requested session does not exist. | false | 66 | flutter_mcp_cli doctor --json |
invalid_command | parser/validation | Command name or argument contract is invalid. | false | 64 | flutter_mcp_cli schema --name <command_name> |
state_store_read_failed | state store | Persistent state read failed. | true | 74 | flutter_mcp_cli doctor --json |
state_store_write_failed | state store | Persistent state write failed. | true | 74 | flutter_mcp_cli doctor --json |
state_lock_timeout | state lock | State lock acquisition timed out. | true | 75 | flutter_mcp_cli doctor --json |
state_lock_conflict | state lock | Conflicting state lock detected. | true | 75 | flutter_mcp_cli doctor --json |
diagnose_failed | diagnostics | Composite diagnose command failed. | true | 69 | flutter_mcp_cli doctor --json |
explain_errors_failed | diagnostics | Error explanation command failed. | true | 69 | flutter_mcp_cli doctor --json |
unsupported_summary_provider | diagnostics | Unsupported summary provider requested. | false | 64 | flutter_mcp_cli doctor --json |
snapshot_not_found | snapshots | Requested snapshot ID does not exist. | false | 66 | flutter_mcp_cli snapshot create --name <snapshot_id> --args '{}' |
snapshot_invalid | snapshots | Snapshot payload is malformed or invalid. | false | 65 | flutter_mcp_cli doctor --json |
bundle_build_failed | bundles | Bundle creation/publish failed. | true | 74 | flutter_mcp_cli doctor --json |
write_blocked | safe writes | Write blocked by --no-overwrite. | false | 73 | Retry without --no-overwrite or choose a new --output/--name. |
doctor_critical_failed | doctor | One or more critical doctor checks failed. | true | 1 | flutter_mcp_cli doctor --json |
unknown_error | fallback | Unknown code fallback. | false | 70 | flutter_mcp_cli doctor --json |