fix(cua-driver/windows): retry transient BuildUpdatedCache failures instead of returning elements=0 (#1881)

[f-trycua]

Problem

get_window_state sometimes returns an empty tree (elements=0) with BuildUpdatedCache failed: Unbekannter Fehler (0x80004005) — even though the same call returned a full tree moments earlier. One misbehaving/transient UIA provider (e.g. a rich-text control rebuilding its automation subtree, or a virtualized list re-realizing items) takes down the entire snapshot, forcing every element_index tool (click, type_text, …) down to pixel coordinates for that window. Fixes #1881.

Root cause

uia/mod.rs did a single BuildUpdatedCache(TreeScope_Subtree) on the window root and hard-failed on any error — no retry, no fallback. A transient E_FAIL from one provider yields a total outage:

let root_elem = match uncached.BuildUpdatedCache(&cache_req) {
    Ok(e) => e,
    Err(e) => return UiaTreeResult { tree_markdown: format!("BuildUpdatedCache failed: {e}"), nodes: Vec::new() },
};

Fix

Retry the bulk cache build up to 3 attempts with a 40 ms backoff before giving up (the issue notes a second call right after frequently succeeds), and report the attempt count in the failure message. This is the issue's suggestion #1 (retry) plus part of #3 (diagnostics).

The per-node partial-tree fallback (suggestion #2 — return elements=N for the subtrees that did resolve, skipping the broken one) is a larger change to the walker and is left as a follow-up.

Verification

• Compile-verified on Windows (MSVC, windows crate): cargo build -p platform-windows recompiled green at commit 17adb54.
• The transient provider error is timing-dependent in real apps and not reproducible on the Session-0 build host; a deterministic harness (a custom IRawElementProviderFragment returning E_FAIL from one child) would make a good regression test — noted in the issue.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes
  • Enhanced reliability of UI automation operations on Windows by implementing resilient retry logic for cache operations that may fail transiently, improving system stability when encountering temporary failures.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Ignored		Jun 23, 2026 9:47am

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: aef4e972-e2c3-466e-ac7e-e5f743dc1962

📥 Commits

Reviewing files that changed from the base of the PR and between c898d7b and 17adb54.

📒 Files selected for processing (1)

• libs/cua-driver/rust/crates/platform-windows/src/uia/mod.rs

---

📝 Walkthrough

Walkthrough

In walk_tree_unsafe, the single BuildUpdatedCache call that returned immediately on failure is replaced with a bounded retry loop. The new code attempts the call up to MAX_ATTEMPTS = 3 times, sleeping 40ms between failures, and only returns the error result after all attempts are exhausted, including the attempt count in the failure message.

Changes

BuildUpdatedCache Retry Logic

Layer / File(s)	Summary
Bounded retry loop for BuildUpdatedCache libs/cua-driver/rust/crates/platform-windows/src/uia/mod.rs	walk_tree_unsafe retries BuildUpdatedCache up to 3 times with a 40ms sleep between attempts; the final error message reports the attempt count instead of failing immediately on the first error.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~5 minutes

Possibly related PRs

• trycua/cua#1606: Modifies the same BuildUpdatedCache call site in the Windows UIA walker, adding a fallback path for subtree cache building — directly adjacent to the retry logic introduced here.

Poem

🐇 One try, two tries, three tries more,
Before we quit and close the door.
A cache that fails may just be shy —
With forty milliseconds, retry!
The tree walks on, no empty floor. 🌳

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately describes the main change: retrying transient BuildUpdatedCache failures instead of returning an empty tree.
Linked Issues check	✅ Passed	The PR implements the retry mechanism with backoff (issue suggestion 1) and enhanced diagnostics showing attempt counts (part of suggestion 3), directly addressing core requirements from #1881.
Out of Scope Changes check	✅ Passed	All changes are scoped to the BuildUpdatedCache retry logic in walk_tree_unsafe, which is directly related to the issue objective.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/windows-uia-cache-retry-1881

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Linux visual regression artifacts

Matrix jobs now run independently. Download visual artifacts from this workflow run.
Each background-GUI job uploads a .gif of the interaction plus two annotated PNGs (<app>.png raw, <app>-atspi.png with AT-SPI element boxes); the cua-driver-linux-som-overlays artifact adds <app>-som.png cua Set-of-Marks overlays:

• cua-driver-linux-cursor-click-gif
• cua-driver-linux-background-terminal-gif
• cua-driver-linux-parallel-drag-xserver
• cua-driver-linux-background-gui-chromium
• cua-driver-linux-background-gui-tk
• cua-driver-linux-background-gui-gtk3-gedit
• cua-driver-linux-background-gui-gtk3-mousepad
• cua-driver-linux-background-gui-gtk3-scite
• cua-driver-linux-background-gui-gtk4-characters
• cua-driver-linux-background-gui-qt5-manuskript
• cua-driver-linux-background-gui-qt5-klog
• cua-driver-linux-background-gui-qt5-openambit
• cua-driver-linux-background-gui-qt6-kate
• cua-driver-linux-background-gui-qt6-kcalc
• cua-driver-linux-background-gui-qt6-okular
• cua-driver-linux-background-gui-qt6-qownnotes
• cua-driver-linux-background-gui-electron-zettlr
• cua-driver-linux-background-gui-electron-joplin
• cua-driver-linux-background-gui-electron-logseq
• cua-driver-linux-som-overlays

Open workflow run and download artifacts