Skip to content

Commit 42f3104

Browse files
committed
docs(agents): document benign Flutter AXTree accessibility log on Windows
The recurring "Failed to update ui::AXTree" log from accessibility_bridge.cc during flutter run -d windows is a known, benign Flutter engine bug (flutter/flutter#182444, #188662), not an FMP defect. Add a root AGENTS.md Never pointer and a detailed subsection in lib/services/AGENTS.md (Windows Sub-Windows) so future agents do not chase it, including the verified do-not-fix list and dev-terminal filtering guidance.
1 parent 649140d commit 42f3104

2 files changed

Lines changed: 54 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,9 @@ Never:
104104
- Do not open or migrate the Isar database through ad-hoc paths.
105105
- Do not add hidden global enabled-source filters for search.
106106
- Do not use direct `Image.network()` / `Image.file()` in UI.
107+
- Do not try to "fix" the benign `Failed to update ui::AXTree` Windows log spam —
108+
it is a known Flutter engine bug (`flutter/flutter#182444`), not an FMP
109+
defect; see `lib/services/AGENTS.md` § Windows Sub-Windows for context.
107110
- Do not commit, amend, rebase, or push unless the user explicitly requests it.
108111

109112
## Architecture Map

‎lib/services/AGENTS.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -185,6 +185,57 @@ Global system hotkeys must require at least one modifier. Validate this in the
185185
model/import path, not only in the recording dialog, because backups can contain
186186
raw `hotkeyConfig` JSON.
187187

188+
### Known benign runtime noise: `Failed to update ui::AXTree`
189+
190+
`flutter run -d windows` repeatedly logs
191+
`[ERROR:flutter/shell/platform/common/accessibility_bridge.cc(114)] Failed to update ui::AXTree, error: <N> will not be in the tree and is not the new root`.
192+
This is a **known Flutter engine bug, not an FMP defect, and it is benign — do
193+
not try to fix it.** Every claim below was verified against primary sources
194+
(engine source, `flutter/flutter` GitHub, Flutter 3.44 release notes) in 2026-07.
195+
196+
- Engine behavior: `AccessibilityBridge::CommitUpdates()` cannot serialize a
197+
semantics-node reparent in a single update, so it does `FML_LOG(ERROR) ... ;
198+
return;`, drops that one update, and re-sends a corrected tree next frame. No
199+
crash, no functional impact. Tracked upstream by `flutter/flutter#182444`
200+
(ListView + Tooltip + OverlayPortal, Windows-only, OPEN as of 2026-07) and
201+
`flutter/flutter#188662` (bridge leaks its `AXTreeManager`). No Flutter
202+
version, including master, fixes it yet.
203+
- Why FMP triggers it: each `desktop_multi_window` sub-window runs its own
204+
Flutter engine (its own `AccessibilityBridge`), and the custom / lyrics title
205+
bars use `IconButton` tooltips + `Semantics`/`ExcludeSemantics` — exactly the
206+
`#182444` reparent pattern. The package multiplies the surface area but is not
207+
itself the bug.
208+
- Scope: the line is C++ `FML_LOG` on platform stderr. It never enters
209+
`AppLogger` / the in-app Log Viewer, and release builds show nothing (no
210+
attached console). It only clutters the dev terminal.
211+
212+
None of these "fix" it — do not do them:
213+
- Upgrade Flutter, `desktop_multi_window`, or `window_manager` solely for this.
214+
- Globally `setSemanticsEnabled(false)` on the main window (kills Narrator/NVDA
215+
a11y app-wide).
216+
- Use the `FLUTTER_A11Y=off` env var or
217+
`FlutterWindows.instance?.setSemanticsEnabled(...)` — these are not real
218+
Flutter APIs (forum fabrication; no engine/framework reference exists).
219+
- Wrap `IconButton` in a `Tooltip(child: ...)` — that is the OverlayPortal
220+
anti-pattern from `#182444`.
221+
222+
When you see it: ignore it. To reduce terminal noise:
223+
224+
```bash
225+
# filter inline (Git Bash) — note this breaks flutter run hot-reload interactivity
226+
flutter run -d windows 2>&1 | grep -vF "Failed to update ui::AXTree"
227+
# PowerShell — same hot-reload caveat
228+
flutter run -d windows 2>&1 | Select-String -NotMatch "Failed to update ui::AXTree"
229+
# keep stdout/stdin interactive, send only stderr to a file
230+
flutter run -d windows 2> run.log
231+
```
232+
233+
VS Code's integrated terminal has no native "hide lines matching a pattern"
234+
filter (verified through v1.107); use one of the pipes above, redirect stderr to
235+
a file, or a capture-and-filter extension (e.g. *Better Terminal Logs*). The
236+
*Filter Lines* extension only operates on editor documents, not the live
237+
terminal, so it does not apply here.
238+
188239
## Image Thumbnail Optimization
189240

190241
`ThumbnailUrlUtils` optimizes image URLs by platform:

0 commit comments

Comments
 (0)