“node with id X not found in a11y tree”

The id is an index into a snapshot, not a handle on the element

Every accessibility-tree tool gives you a flattened view of the live tree at one instant. To make that view addressable it tags each node with an id: a number, a ref like @e7, a backend node id from the Chrome DevTools Protocol, or a UIA RuntimeId. That id is meaningful only inside the snapshot it was minted in. It is not a stable pointer to the button on screen; it is a row number in a table that gets thrown away and rebuilt.

So the moment the tree is rebuilt, the table is regenerated and the row numbers shuffle. Your saved id now points at nothing, or worse, at a different element. The tool detects the first case and raises node with id X not found in a11y tree. The same class of error shows up worded slightly differently across stacks: “Could not find node with id N in commit tree” in React DevTools, “Ref not found: @eN” in snapshot-ref browser agents, “Unregistered node” in some UI frameworks. Different words, one cause.

The exact moment it goes stale

Here is the lifecycle of a single click that fails. The id is born valid and dies between two steps you did not think changed anything.

Nothing is broken in the app. The button is still on screen. The only thing that is wrong is that you are holding a number from a snapshot that no longer exists.

Recover right now, with the tool you already have

If you are on a snapshot-id API and just need the run to pass, the fix is mechanical. Shorten the distance between capture and action so the id has no time to expire.

The durable fix: bind to a selector, re-resolve at action time

Re-snapshotting treats the symptom. The cause is that your action is coupled to an ephemeral id. Remove the id from the contract entirely: describe the element by what it is (its role and name), and let the framework re-find it against the live tree at the instant you act. There is then no value to carry across a state change, so nothing can go stale.

# the stale-id pattern (every snapshot-id tool)
snapshot = agent.snapshot()              # node 42 = the Save button, right now
save_id  = find(snapshot, "Save").id     # 42
agent.click(modal_appeared_then())       # tree rebuilds, ids reassigned
agent.click_by_id(save_id)               # 42 is gone
#   -> "node with id 42 not found in a11y tree"

// the durable-selector pattern (Terminator)
let app = desktop.application("notepad")?;

// the selector is a *description*, not an index into a past snapshot
app.locator("role:Button|name:Save")?
   .click(Some(Duration::from_secs(5)))   // re-resolved against the LIVE tree here
   .await?;
// no id is ever held across an action, so none can go stale

This is the design Terminator ships with. The selector is parsed into a semantic query, not a snapshot index. Its variants are role-and-name, automation id, name, text, attributes, and even relational ones like RightOf and Below an anchor element. None of them is an id from a past capture.

This is not only a browser problem

Most writing about this error assumes you are inside a browser, because that is where snapshot-ref agents are most common. But the failure mode is a property of any accessibility tree, and native desktop trees churn just as hard: a Windows UIA RuntimeId is invalidated when the control is re-created, an AX element reference on macOS dies when the app rebuilds a view or switches tabs, and a line-of-business app that redraws a grid throws away every node you were holding.

Terminator targets the whole OS rather than a single tab, so the stale-binding question matters across every app on the desktop, not just the page in front of you. The answer is the same everywhere: do not hold a reference into a tree that moves. Hold a description and re-resolve it. That is why the same role:Button|name:Save selector is portable across the Windows UIA adapter and the macOS AX adapter without you ever touching a platform-specific id.

Frequently asked questions

Terminator is an open-source desktop automation framework for Windows and macOS that drives apps through native accessibility APIs, with a Playwright-shaped API for the whole OS and an MCP server for AI agents. The source is on GitHub. For more on how snapshot refs go stale in browser agents, the agent-browser docs describe the same re-snapshot recovery for the browser case.