[web][a11y] Semantic tree gets corrupted after UI updates #175180
Description
Steps to reproduce
Description
We are developing a Flutter Web application that heavily relies on semantics labels (for automated tests and accessibility) and the Focus widget (for keyboard navigation).
Occasionally, after certain UI updates, the semantic tree becomes corrupted:
- Console shows multiple errors.
- Old semantics nodes are not removed from the tree.
- Our automated tests fail, and it’s very likely that screen readers would also break in this state.
The problem seems non-deterministic and may depend on asynchronous operations during UI updates. It is hard to reproduce consistently, but we’ve managed to isolate two minimal scenarios.
Scenario 1
- Tap “Show loading”.
- When the loader is replaced with text, a console error appears. By itself, this error does not immediately corrupt the semantic tree.
- However, if a dropdown (or other popup) is opened during loading, the error causes the semantic tree to break.
- In DevTools, you can see that on subsequent dropdown openings, elements are no longer removed from the tree.
Workaround: Replace the Focus widget with a FocusScope.
Scenario 2
- Open a screen and wait until the initial loading finishes.
- When the loader is replaced with text, a console error occurs:
Child #xx is missing in the tree - After this, opening a dropdown produces new errors and leaves elements stuck in the semantic tree.
Workaround: Wrap the two SVG icons used in this scenario with ExcludeSemantics.
We found workarounds that avoid the issue in some cases. However, finding these fixes is often a trial-and-error process and time-consuming. If this is a root issue in Flutter semantics, a framework-level fix would be much more reliable.
Expected results
- The semantic tree should stay consistent after UI changes.
- Old semantics nodes should be properly disposed.
- No errors should appear in the console.
- Both automated tests and screen readers should continue to function normally.
Actual results
- Console reports errors (e.g. “Child #xx is missing in the tree”).
- Semantics nodes accumulate and are not removed.
- Semantic tree becomes corrupted.
- Automated tests fail, and accessibility is likely broken.
Code sample
Code sample
import 'package:flutter/material.dart';
import 'package:flutter/semantics.dart';
import 'package:flutter_svg/svg.dart';
void main() {
WidgetsFlutterBinding.ensureInitialized();
SemanticsBinding.instance.ensureSemantics();
runApp(const MyApp());
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
return MaterialApp(
theme: ThemeData(),
home: Builder(
builder: (context) {
return Scaffold(
appBar: AppBar(
title: const Text('Semantics Bugs in Flutter Web'),
),
body: Padding(
padding: const EdgeInsets.all(20),
child: Column(
spacing: 20,
children: [
ElevatedButton(
onPressed: () => _openCase1(context),
child: const Text('Open Case 1'),
),
ElevatedButton(
onPressed: () => _openCase2(context),
child: const Text('Open Case 2'),
),
],
),
),
);
},
),
);
}
void _openCase1(BuildContext context) {
Navigator.push(
context,
PageRouteBuilder<void>(
opaque: false,
pageBuilder: (_, __, ___) => const Case1Screen(),
),
);
}
void _openCase2(BuildContext context) {
Navigator.push(
context,
PageRouteBuilder<void>(
opaque: false,
pageBuilder: (_, __, ___) => const Case2Screen(),
),
);
}
}
class Case1Screen extends StatefulWidget {
const Case1Screen({super.key});
@override
State<Case1Screen> createState() => _Case1ScreenState();
}
class _Case1ScreenState extends State<Case1Screen> {
bool _isLoading = false;
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(
title: const Text('Case 1'),
),
body: Padding(
padding: const EdgeInsets.all(50),
child: Row(
spacing: 20,
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Column(
children: [
ElevatedButton(
onPressed: _showLoading,
child: const Text('Show loading'),
),
Semantics(
container: true,
label: 'table',
child: Column(
children: [
// Workaround: change this Focus to FocusScope
const Focus(
child: SingleChildScrollView(
child: Text('column header'),
),
),
if (_isLoading)
const CircularProgressIndicator()
else
const Focus(
child: SingleChildScrollView(
child: Text('item data'),
),
),
],
),
),
],
),
DropdownButton(
value: 1,
items: [
const DropdownMenuItem(
value: 1,
child: Text(
'item1',
semanticsLabel: 'dropdownItem1',
),
),
const DropdownMenuItem(
value: 2,
child: Text(
'item2',
semanticsLabel: 'dropdownItem2',
),
),
],
onChanged: (_) {},
),
],
),
),
);
}
void _showLoading() {
setState(() {
_isLoading = true;
});
Future.delayed(
const Duration(seconds: 3),
() {
if (mounted) {
setState(() {
_isLoading = false;
});
}
},
);
}
}
class Case2Screen extends StatefulWidget {
const Case2Screen({super.key});
@override
State<Case2Screen> createState() => _Case2ScreenState();
}
class _Case2ScreenState extends State<Case2Screen> {
bool _isLoading = false;
@override
void initState() {
super.initState();
_showLoading();
}
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(
title: const Text('Case 2'),
),
body: Padding(
padding: const EdgeInsets.all(50),
child: Row(
spacing: 20,
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Semantics(
container: true,
label: 'table',
child: Column(
children: [
Focus(
child: Semantics(
container: true,
label: 'header',
child: Row(
spacing: 5,
children: <Widget>[
const Text('column header'),
// Workaround: wrap this Row in ExcludeSemantics
Row(
children: <Widget>[
SvgPicture.asset(
'assets/flutter_logo.svg',
width: 15,
height: 15,
),
SvgPicture.asset(
'assets/flutter_logo.svg',
width: 15,
height: 15,
),
],
),
],
),
),
),
if (_isLoading)
const CircularProgressIndicator()
else
const Focus(
child: Text('item data'),
),
],
),
),
DropdownButton(
value: 1,
items: [
const DropdownMenuItem(
value: 1,
child: Text(
'item1',
semanticsLabel: 'dropdownItem1',
),
),
const DropdownMenuItem(
value: 2,
child: Text(
'item2',
semanticsLabel: 'dropdownItem2',
),
),
],
onChanged: (_) {},
),
],
),
),
);
}
void _showLoading() {
setState(() {
_isLoading = true;
});
Future.delayed(
const Duration(seconds: 3),
() {
if (mounted) {
setState(() {
_isLoading = false;
});
}
},
);
}
}
Screenshots or Video
Video case 1
scenario1.mov
Video case 2
scenario2.mov
Logs
Scenario 1 initial error
======== Exception caught by scheduler library =====================================================
The following TypeErrorImpl was thrown during a scheduler callback:
Unexpected null value.
When the exception was thrown, this was the stack:
dart-sdk/lib/_internal/js_dev_runtime/private/ddc_runtime/errors.dart 274:3 throw_
dart-sdk/lib/_internal/js_dev_runtime/private/ddc_runtime/operations.dart 948:18 nullCheck
lib/_engine/engine/semantics/semantics.dart 2242:53 recomputeChildrenAdjustment
lib/_engine/engine/semantics/semantics.dart 2304:5 updateChildrenPositionAndSize
lib/_engine/engine/semantics/scrollable.dart 134:7 <fn>
lib/_engine/engine/semantics/semantics.dart 2888:11 [_finalizeTree]
lib/_engine/engine/semantics/semantics.dart 3002:5 updateSemantics
lib/_engine/engine/window.dart 109:5 updateSemantics
package:flutter/src/rendering/view.dart 386:5 updateSemantics
package:flutter/src/rendering/binding.dart 268:48 <fn>
package:flutter/src/semantics/semantics.dart 4358:22 sendSemanticsUpdate
package:flutter/src/rendering/object.dart 1499:7 flushSemantics
package:flutter/src/rendering/object.dart 1501:14 flushSemantics
package:flutter/src/rendering/binding.dart 636:7 drawFrame
package:flutter/src/widgets/binding.dart 1261:13 drawFrame
package:flutter/src/rendering/binding.dart 495:5 [_handlePersistentFrameCallback]
dart-sdk/lib/_internal/js_dev_runtime/private/ddc_runtime/operations.dart 118:77 tear
package:flutter/src/scheduler/binding.dart 1434:7 [_invokeFrameCallback]
package:flutter/src/scheduler/binding.dart 1347:9 handleDrawFrame
package:flutter/src/scheduler/binding.dart 1200:5 [_handleDrawFrame]
dart-sdk/lib/_internal/js_dev_runtime/private/ddc_runtime/operations.dart 118:77 tear
lib/_engine/engine/platform_dispatcher.dart 1522:5 invoke
lib/_engine/engine/platform_dispatcher.dart 265:5 invokeOnDrawFrame
lib/_engine/engine/frame_service.dart 192:32 [_renderFrame]
lib/_engine/engine/frame_service.dart 99:9 <fn>
dart-sdk/lib/async/zone.dart 1849:54 runUnary
dart-sdk/lib/async/zone.dart 1804:26 <fn>
dart-sdk/lib/_internal/js_dev_runtime/patch/js_allow_interop_patch.dart 224:27 _callDartFunctionFast1
====================================================================================================Scenario 1 example error after tree is broken
======== Exception caught by scheduler library =====================================================
The following assertion was thrown during a scheduler callback:
Assertion failed: org-dartlang-sdk:///lib/_engine/engine/semantics/semantics.dart:2377:9
child != null
"visitDepthFirstInTraversalOrder must only be called after the node tree has been established. However, child #13 does not have its SemanticsNode created at the time this method was called."
When the exception was thrown, this was the stack:
dart-sdk/lib/_internal/js_dev_runtime/private/ddc_runtime/errors.dart 274:3 throw_
dart-sdk/lib/_internal/js_dev_runtime/private/ddc_runtime/errors.dart 44:3 assertFailed
lib/_engine/engine/semantics/semantics.dart 2377:14 [_visitDepthFirstInTraversalOrder]
lib/_engine/engine/semantics/semantics.dart 2383:17 [_visitDepthFirstInTraversalOrder]
lib/_engine/engine/semantics/semantics.dart 2383:17 [_visitDepthFirstInTraversalOrder]
lib/_engine/engine/semantics/semantics.dart 2357:5 visitDepthFirstInTraversalOrder
lib/_engine/engine/semantics/semantics.dart 2863:21 [_finalizeTree]
lib/_engine/engine/semantics/semantics.dart 3002:5 updateSemantics
lib/_engine/engine/window.dart 109:5 updateSemantics
package:flutter/src/rendering/view.dart 386:5 updateSemantics
package:flutter/src/rendering/binding.dart 268:48 <fn>
package:flutter/src/semantics/semantics.dart 4358:22 sendSemanticsUpdate
package:flutter/src/rendering/object.dart 1499:7 flushSemantics
package:flutter/src/rendering/object.dart 1501:14 flushSemantics
package:flutter/src/rendering/binding.dart 636:7 drawFrame
package:flutter/src/widgets/binding.dart 1261:13 drawFrame
package:flutter/src/rendering/binding.dart 495:5 [_handlePersistentFrameCallback]
dart-sdk/lib/_internal/js_dev_runtime/private/ddc_runtime/operations.dart 118:77 tear
package:flutter/src/scheduler/binding.dart 1434:7 [_invokeFrameCallback]
package:flutter/src/scheduler/binding.dart 1347:9 handleDrawFrame
package:flutter/src/scheduler/binding.dart 1200:5 [_handleDrawFrame]
dart-sdk/lib/_internal/js_dev_runtime/private/ddc_runtime/operations.dart 118:77 tear
lib/_engine/engine/platform_dispatcher.dart 1522:5 invoke
lib/_engine/engine/platform_dispatcher.dart 265:5 invokeOnDrawFrame
lib/_engine/engine/frame_service.dart 192:32 [_renderFrame]
lib/_engine/engine/frame_service.dart 99:9 <fn>
dart-sdk/lib/async/zone.dart 1849:54 runUnary
dart-sdk/lib/async/zone.dart 1804:26 <fn>
dart-sdk/lib/_internal/js_dev_runtime/patch/js_allow_interop_patch.dart 224:27 _callDartFunctionFast1
====================================================================================================Scenario 2 initial error
======== Exception caught by scheduler library =====================================================
The following assertion was thrown during a scheduler callback:
Assertion failed: "Child #25 is missing in the tree."
When the exception was thrown, this was the stack:
dart-sdk/lib/_internal/js_dev_runtime/private/ddc_runtime/errors.dart 274:3 throw_
lib/_engine/engine/semantics/semantics.dart 3035:15 <fn>
dart-sdk/lib/_internal/js_dev_runtime/private/linked_hash_map.dart 21:7 forEach
lib/_engine/engine/semantics/semantics.dart 3023:7 <fn>
lib/_engine/engine/semantics/semantics.dart 3062:14 updateSemantics
lib/_engine/engine/window.dart 109:5 updateSemantics
package:flutter/src/rendering/view.dart 386:5 updateSemantics
package:flutter/src/rendering/binding.dart 268:48 <fn>
package:flutter/src/semantics/semantics.dart 4358:22 sendSemanticsUpdate
package:flutter/src/rendering/object.dart 1499:7 flushSemantics
package:flutter/src/rendering/object.dart 1501:14 flushSemantics
package:flutter/src/rendering/binding.dart 636:7 drawFrame
package:flutter/src/widgets/binding.dart 1261:13 drawFrame
package:flutter/src/rendering/binding.dart 495:5 [_handlePersistentFrameCallback]
dart-sdk/lib/_internal/js_dev_runtime/private/ddc_runtime/operations.dart 118:77 tear
package:flutter/src/scheduler/binding.dart 1434:7 [_invokeFrameCallback]
package:flutter/src/scheduler/binding.dart 1347:9 handleDrawFrame
package:flutter/src/scheduler/binding.dart 1200:5 [_handleDrawFrame]
dart-sdk/lib/_internal/js_dev_runtime/private/ddc_runtime/operations.dart 118:77 tear
lib/_engine/engine/platform_dispatcher.dart 1522:5 invoke
lib/_engine/engine/platform_dispatcher.dart 265:5 invokeOnDrawFrame
lib/_engine/engine/frame_service.dart 192:32 [_renderFrame]
lib/_engine/engine/frame_service.dart 99:9 <fn>
dart-sdk/lib/async/zone.dart 1849:54 runUnary
dart-sdk/lib/async/zone.dart 1804:26 <fn>
dart-sdk/lib/_internal/js_dev_runtime/patch/js_allow_interop_patch.dart 224:27 _callDartFunctionFast1
====================================================================================================Scenario 2 example errors after tree is broken
======== Exception caught by scheduler library =====================================================
The following assertion was thrown during a scheduler callback:
Assertion failed: org-dartlang-sdk:///lib/_engine/engine/semantics/semantics.dart:2377:9
child != null
"visitDepthFirstInTraversalOrder must only be called after the node tree has been established. However, child #25 does not have its SemanticsNode created at the time this method was called."
When the exception was thrown, this was the stack:
dart-sdk/lib/_internal/js_dev_runtime/private/ddc_runtime/errors.dart 274:3 throw_
dart-sdk/lib/_internal/js_dev_runtime/private/ddc_runtime/errors.dart 44:3 assertFailed
lib/_engine/engine/semantics/semantics.dart 2377:14 [_visitDepthFirstInTraversalOrder]
lib/_engine/engine/semantics/semantics.dart 2383:17 [_visitDepthFirstInTraversalOrder]
lib/_engine/engine/semantics/semantics.dart 2383:17 [_visitDepthFirstInTraversalOrder]
lib/_engine/engine/semantics/semantics.dart 2383:17 [_visitDepthFirstInTraversalOrder]
lib/_engine/engine/semantics/semantics.dart 2357:5 visitDepthFirstInTraversalOrder
lib/_engine/engine/semantics/semantics.dart 2863:21 [_finalizeTree]
lib/_engine/engine/semantics/semantics.dart 3002:5 updateSemantics
lib/_engine/engine/window.dart 109:5 updateSemantics
package:flutter/src/rendering/view.dart 386:5 updateSemantics
package:flutter/src/rendering/binding.dart 268:48 <fn>
package:flutter/src/semantics/semantics.dart 4358:22 sendSemanticsUpdate
package:flutter/src/rendering/object.dart 1499:7 flushSemantics
package:flutter/src/rendering/object.dart 1501:14 flushSemantics
package:flutter/src/rendering/binding.dart 636:7 drawFrame
package:flutter/src/widgets/binding.dart 1261:13 drawFrame
package:flutter/src/rendering/binding.dart 495:5 [_handlePersistentFrameCallback]
dart-sdk/lib/_internal/js_dev_runtime/private/ddc_runtime/operations.dart 118:77 tear
package:flutter/src/scheduler/binding.dart 1434:7 [_invokeFrameCallback]
package:flutter/src/scheduler/binding.dart 1347:9 handleDrawFrame
package:flutter/src/scheduler/binding.dart 1200:5 [_handleDrawFrame]
dart-sdk/lib/_internal/js_dev_runtime/private/ddc_runtime/operations.dart 118:77 tear
lib/_engine/engine/platform_dispatcher.dart 1522:5 invoke
lib/_engine/engine/platform_dispatcher.dart 265:5 invokeOnDrawFrame
lib/_engine/engine/frame_service.dart 192:32 [_renderFrame]
lib/_engine/engine/frame_service.dart 99:9 <fn>
dart-sdk/lib/async/zone.dart 1849:54 runUnary
dart-sdk/lib/async/zone.dart 1804:26 <fn>
dart-sdk/lib/_internal/js_dev_runtime/patch/js_allow_interop_patch.dart 224:27 _callDartFunctionFast1
====================================================================================================
======== Exception caught by scheduler library =====================================================
The following StateError was thrown during a scheduler callback:
Bad state: Semantics node map was inconsistent after update:
BEFORE: The semantics node map is inconsistent:
Nodes in tree:
0: [1]
1: [20, 19]
20: []
19: []
Nodes in map: [0, 1, 8, 9, 13, 14, 10, 15, 16, 17, 18, 19, 20, 21, 22, 25, 23, 24]
AFTER: The semantics node map is inconsistent:
Nodes in tree:
0: [1]
1: [8]
8: [14, 9, 13]
14: [15, 16]
15: []
16: []
9: [17, 18]
17: [10]
10: [11, 12]
11: []
12: []
18: []
13: []
Nodes in map: [0, 1, 8, 19, 20, 21, 22, 25, 23, 24, 11, 12]
When the exception was thrown, this was the stack:
dart-sdk/lib/_internal/js_dev_runtime/private/ddc_runtime/errors.dart 274:3 throw_
lib/_engine/engine/semantics/semantics.dart 3013:9 <fn>
lib/_engine/engine/semantics/semantics.dart 3062:14 updateSemantics
lib/_engine/engine/window.dart 109:5 updateSemantics
package:flutter/src/rendering/view.dart 386:5 updateSemantics
package:flutter/src/rendering/binding.dart 268:48 <fn>
package:flutter/src/semantics/semantics.dart 4358:22 sendSemanticsUpdate
package:flutter/src/rendering/object.dart 1499:7 flushSemantics
package:flutter/src/rendering/object.dart 1501:14 flushSemantics
package:flutter/src/rendering/binding.dart 636:7 drawFrame
package:flutter/src/widgets/binding.dart 1261:13 drawFrame
package:flutter/src/rendering/binding.dart 495:5 [_handlePersistentFrameCallback]
dart-sdk/lib/_internal/js_dev_runtime/private/ddc_runtime/operations.dart 118:77 tear
package:flutter/src/scheduler/binding.dart 1434:7 [_invokeFrameCallback]
package:flutter/src/scheduler/binding.dart 1347:9 handleDrawFrame
package:flutter/src/scheduler/binding.dart 1200:5 [_handleDrawFrame]
dart-sdk/lib/_internal/js_dev_runtime/private/ddc_runtime/operations.dart 118:77 tear
lib/_engine/engine/platform_dispatcher.dart 1522:5 invoke
lib/_engine/engine/platform_dispatcher.dart 265:5 invokeOnDrawFrame
lib/_engine/engine/frame_service.dart 192:32 [_renderFrame]
lib/_engine/engine/frame_service.dart 99:9 <fn>
dart-sdk/lib/async/zone.dart 1849:54 runUnary
dart-sdk/lib/async/zone.dart 1804:26 <fn>
dart-sdk/lib/_internal/js_dev_runtime/patch/js_allow_interop_patch.dart 224:27 _callDartFunctionFast1
====================================================================================================Flutter Doctor output
Doctor output
[✓] Flutter (Channel stable, 3.35.3, on macOS 15.6 24G84 darwin-arm64, locale en-US) [420ms]
• Flutter version 3.35.3 on channel stable at /Users/user/Developer/flutter
• Upstream repository https://github.com/flutter/flutter.git
• Framework revision a402d9a437 (6 days ago), 2025-09-03 14:54:31 -0700
• Engine revision ddf47dd3ff
• Dart version 3.9.2
• DevTools version 2.48.0
• Feature flags: enable-web, enable-linux-desktop, enable-macos-desktop, enable-windows-desktop, enable-android, enable-ios, cli-animations, enable-lldb-debugging
[✓] Android toolchain - develop for Android devices (Android SDK version 35.0.0) [1,826ms]
• Android SDK at /Users/user/Library/Android/sdk
• Emulator version 36.1.9.0 (build_id 13823996) (CL:N/A)
• Platform android-35, build-tools 35.0.0
• Java binary at: /Applications/Android Studio.app/Contents/jbr/Contents/Home/bin/java
This is the JDK bundled with the latest Android Studio installation on this machine.
To manually set the JDK path, use: `flutter config --jdk-dir="path/to/jdk"`.
• Java version OpenJDK Runtime Environment (build 21.0.7+-13880790-b1038.58)
• All Android licenses accepted.
[✓] Xcode - develop for iOS and macOS (Xcode 16.4) [1,007ms]
• Xcode at /Applications/Xcode.app/Contents/Developer
• Build 16F6
• CocoaPods version 1.16.2
[✓] Chrome - develop for the web [22ms]
• Chrome at /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
[✓] Android Studio (version 2025.1) [22ms]
• Android Studio at /Applications/Android Studio.app/Contents
• Flutter plugin can be installed from:
🔨 https://plugins.jetbrains.com/plugin/9212-flutter
• Dart plugin can be installed from:
🔨 https://plugins.jetbrains.com/plugin/6351-dart
• Java version OpenJDK Runtime Environment (build 21.0.7+-13880790-b1038.58)
[✓] IntelliJ IDEA Community Edition (version 2024.2.3) [21ms]
• IntelliJ at /Applications/IntelliJ IDEA CE.app
• Flutter plugin can be installed from:
🔨 https://plugins.jetbrains.com/plugin/9212-flutter
• Dart plugin can be installed from:
🔨 https://plugins.jetbrains.com/plugin/6351-dart
[✓] Connected device (2 available) [6.2s]
• macOS (desktop) • macos • darwin-arm64 • macOS 15.6 24G84 darwin-arm64
• Chrome (web) • chrome • web-javascript • Google Chrome 140.0.7339.133
[✓] Network resources [222ms]
• All expected network resources are available.
• No issues found!Metadata
Metadata
Assignees
Labels
Accessibility, e.g. VoiceOver or TalkBack. (aka a11y)flutter/packages/flutter/material repository.Found to occur in 3.35Found to occur in 3.37flutter/packages/flutter repository. See also f: labels.The issue has been confirmed reproducible and is ready to work onWeb applications specificallyIssue is closed as already fixed in a newer versionOwned by Web platform teamThere is a workaround available to overcome the issue