You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 42f3104
Browse filesBrowse the repository at this point in the historyBrowse files
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.
Copy file name to clipboardExpand all lines: lib/services/AGENTS.md
+51Lines changed: 51 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -185,6 +185,57 @@ Global system hotkeys must require at least one modifier. Validate this in the
185
185
model/import path, not only in the recording dialog, because backups can contain
186
186
raw `hotkeyConfig` JSON.
187
187
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
+
188
239
## Image Thumbnail Optimization
189
240
190
241
`ThumbnailUrlUtils` optimizes image URLs by platform:
0 commit comments