Semantics Assertion Regression in Flutter 3.47: What Happened and How to Fix It

In August 2026, a significant accessibility regression was discovered in Flutter 3.47 that affected the semantics system — the backbone of screen reader support. This issue caused assertion failures when MergeSemantics was used alongside widgets with sibling merge groups, impacting hundreds of widget tests across the Flutter ecosystem.

The Issue

The regression was reported as GitHub Issue #191095 by developer Pante while migrating the Forui UI library from Flutter 3.44 to 3.47.

The Error

'package:flutter/src/semantics/semantics.dart': Failed assertion: line 3862 pos 16:
'node.isMergedIntoParent': is not true.

The Root Cause

The issue occurred when:

1. A MergeSemantics ancestor was present
2. A descendant widget’s SemanticsConfiguration.childConfigurationsDelegate produced a sibling merge group

The InputDecorator widget (used internally by TextField) has one such delegate — it routes through _AffixText, which sits under an AnimatedOpacity. When a TextField with a prefix was placed inside a MergeSemantics, the assertion failed.

Simple Reproduction

import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';

void main() {
  testWidgets('MergeSemantics + sibling merge group', (tester) async {
    final focus = FocusNode();
    addTearDown(focus.dispose);

    await tester.pumpWidget(
      MaterialApp(
        home: Material(
          child: MergeSemantics(
            child: TextField(
              focusNode: focus,
              decoration: const InputDecoration(
                prefix: SizedBox(width: 12),
              ),
            ),
          ),
        ),
      ),
    );

    focus.requestFocus();
    await tester.pumpAndSettle();

    expect(tester.takeException(), isNull);
  });
}

This simple code — putting a TextField with a prefix inside a MergeSemantics — was enough to trigger the assertion.

Impact

The regression was classified as P2 (important but not critical) and affected:

• Any widget using InputDecorator with affixes inside a MergeSemantics
• Roughly 200 failing widget tests in the Forui library alone
• Potentially any Flutter app or package using these patterns

The Fix

The Flutter accessibility team (led by chunhtai) identified the issue in the rendering layer. The fix involved updating how the semantics system accounts for merge groups:

// Before (broken)
node.isMergedIntoParent = parentData?.mergeIntoParent ?? false;

// After (fixed)
node.isMergedIntoParent =
    configProvider.effective.isMergingSemanticsOfDescendants ||
    (parentData?.mergeIntoParent ?? false);

The key insight: the sibling node needed to account for the merge it was about to be placed inside, not just the merge imposed from above.

The Fix was Merged in PR #191587

The fix was included in a subsequent Flutter patch release, and the issue was closed as fixed.

Lessons Learned

1. Accessibility Systems Are Complex

The semantics system in Flutter is a parallel tree that must stay synchronized with the widget tree. Edge cases in merging behavior can have far-reaching effects.

2. Community Testing Matters

This issue was caught by a library author migrating to the new version — exactly the kind of real-world testing that catches regressions. The Flutter ecosystem’s diverse usage patterns act as a natural safety net.

3. Assertions Catch Real Bugs

The assertion failure was by design — it caught an invalid state before it could cause silent misbehavior. Without assertions, screen readers would have received incorrect semantic information.

4. Migrations Can Surface Hidden Issues

Upgrading Flutter versions is a good time to run your full test suite. This regression only manifested when specific widget combinations were used together.

How to Protect Your App

Run Tests After Upgrades

# After upgrading Flutter
flutter pub get
flutter test

Test Accessibility Manually

# Enable screen reader and test key flows
# VoiceOver: Settings > Accessibility > VoiceOver
# TalkBack: Settings > Accessibility > TalkBack

Use the Semantics Debugger

MaterialApp(
  showSemanticsDebugger: kDebugMode,
  // ...
)

Stay Updated

Follow the Flutter release notes and breaking changes to know when accessibility-related fixes are included.

Resources

• Issue #191095
• PR #191587 - The Fix
• Flutter Semantics Documentation

This regression reminds us that accessibility is an active area of development in Flutter. The community’s ability to quickly identify, report, and fix such issues demonstrates the maturity and responsiveness of the Flutter ecosystem.