WinGuiMcp tools return structured errors so agents can retry, re-snapshot, or escalate without parsing free-text messages.
Failed tool calls return MCP tool errors with this JSON shape in the message content:
{
"ok": false,
"code": "ElementNotFound",
"message": "Ref w1e42 is stale; take a new snapshot.",
"details": {
"ref": "w1e42",
"stale": true,
"snapshotId": "550e8400-e29b-41d4-a716-446655440000"
}
}Successful calls may include warnings (not failures):
{
"ok": true,
"_warning": "Action executed via SendInput, but UI state remains unaltered. Verify target or wait for latency."
}| Code | Severity | When | Agent recovery hint |
|---|---|---|---|
ElementNotFound |
recoverable | Ref unknown, stale, or locator matched nothing | Call snapshot or refine find_element criteria |
Ambiguous |
recoverable | Locator matched multiple nodes | Narrow locator (automationId, nth, parent context) |
PatternNotSupported |
recoverable | Requested action needs a UIA pattern the element lacks | Retry with click (SendInput fallback) or pick another element |
ElementNotEnabled |
recoverable | Target exists but enabled: false |
Wait or find alternate control |
VisibilityMismatch |
recoverable | Target exists but offscreen, hidden, or zero-size bbox | Enable includeOffscreen, scroll into view, or pick visible sibling |
UIPIBlocked |
hard | Target process higher integrity than server | Relaunch server elevated; see security.md |
SecureDesktop |
hard | UAC / Winlogon / locked desktop | User must dismiss dialog or unlock session |
Timeout |
recoverable | wait_for exceeded |
Increase timeout, re-snapshot, or change condition |
WindowGone |
recoverable | HWND invalid or window closed | list_windows and re-attach |
FocusFailed |
recoverable | Could not foreground target window | Call focus_window; check if minimized |
InvalidArgument |
client | Malformed params or unknown enum | Fix request schema |
CVLowConfidence |
recoverable | Phase 3: vision detection below threshold | Retry with useVision: true or manual screenshot |
CaptureFailed |
recoverable | Screenshot or WGC capture error | Retry; check if window is occluded |
LaunchFailed |
recoverable | launch_app could not start process |
Verify path/AUMID and permissions |
ConfirmationRequired |
hard | Phase 4: destructive action blocked pending user ack | User confirms via client; retry with confirmationId |
InternalError |
hard | Unexpected server exception | Log and retry once; report if persistent |
ScenarioInvalid |
client | Scenario file, params or expression malformed; unknown param | Fix the file or params; validate_scenario lists every problem |
StepNotFound |
client | A step names a tool or ns.step no provider serves |
Check list_scenarios / tools.md names |
AssertionFailed |
recoverable | An assert, expect or fail step was false |
Inspect the receipt; adjust the app state or the scenario |
WritesNotAllowed |
client | A non-read-only step ran without allowWrites |
Review the scenario, then rerun with allowWrites: true |
TargetNotAllowed |
hard | An actuating step hit a window outside target.processes, a restricted system app, or a stale handle; or the scenario declares no target |
Fix target or the step; never widen it to system apps |
GuardFailed |
recoverable | A step's guard: foreground check failed; nothing was sent |
Wait, refocus, or re-capture; then resume or rerun |
ResumeTokenInvalid |
client | Unknown, used, expired or forged token; scenario changed; secret param missing | Start a new run |
- recoverable — Agent should adapt strategy and retry.
- hard — Requires environment change (elevation, user action, config).
- client — Fix the tool call; no retry without changing input.
Errors may include machine-readable context for agents and trajectory logs:
| Field | When |
|---|---|
selector / by, value |
Locator failures |
backend |
"uia", "msaa", "cv", "sendinput" — last resolution path attempted |
candidates |
Short list of { ref, name, role } on Ambiguous |
traceId |
Links to observability log entry |
Landscape survey (research/deep-research-report.md) uses alternate names — map to WinGuiMcp codes:
| Research term | WinGuiMcp code |
|---|---|
AmbiguousMatch |
Ambiguous |
StaleElement |
ElementNotFound (details.stale: true) |
ActionNotSupported |
PatternNotSupported |
FocusDenied |
FocusFailed |
PrivilegeBoundary |
UIPIBlocked |
WindowClosed |
WindowGone |
LowConfidenceVisionMatch |
CVLowConfidence |
TimeoutExceeded |
Timeout |
| Tool | Common codes |
|---|---|
snapshot |
WindowGone, CaptureFailed, UIPIBlocked |
find_element |
ElementNotFound, Ambiguous, Timeout |
get_properties |
ElementNotFound |
click, type_text, set_value |
ElementNotFound, PatternNotSupported, ElementNotEnabled, VisibilityMismatch, UIPIBlocked, FocusFailed |
hotkey |
InvalidArgument, FocusFailed, UIPIBlocked |
focus_window |
WindowGone, FocusFailed, UIPIBlocked |
launch_app |
LaunchFailed |
wait_for |
Timeout, WindowGone |
screenshot |
WindowGone, CaptureFailed |
Inspired by VLAA-GUI completeness verification. Specified in this catalog; emitted by the server starting Phase 2 (not required for Phase 1 MVP).
Emitted on success when:
| Condition | _warning text |
|---|---|
| Click/type had no detectable UI tree delta within 500 ms | UI state unchanged after action |
| SendInput used instead of UIA pattern | Action used synthetic input fallback |
| Target was offscreen; scroll attempted first | Element was offscreen; scrolled into view |
Warnings do not set ok: false. Agents should treat them as signals to verify task completion before stopping.
When find_element matches multiple nodes and nth is not sufficient:
{
"ok": false,
"code": "Ambiguous",
"message": "Locator matched 3 elements; narrow criteria or set nth.",
"details": {
"matchCount": 3,
"refs": ["w1e5", "w1e12", "w1e19"]
}
}When ref was issued in snapshot A but the current session snapshot is B:
{
"ok": false,
"code": "ElementNotFound",
"message": "Ref w1e42 is stale; take a new snapshot.",
"details": {
"ref": "w1e42",
"stale": true,
"expectedSnapshotId": "…current…",
"refSnapshotId": "…original…"
}
}When input or UIA cross-process call is blocked by integrity level:
{
"ok": false,
"code": "UIPIBlocked",
"message": "Cannot interact with elevated process 'Task Manager' (PID 1234). Run WinGuiMcp as Administrator.",
"details": {
"targetProcess": "Taskmgr.exe",
"targetPid": 1234,
"serverElevated": false
}
}See security.md for operational guidance.