Clarified why initState cannot depend on inherited widgets.

Flutter issue #105705 reported confusing wording in an inherited-widget diagnostic. I updated the explanation in the error message and the initState API documentation, then expanded the existing test to check what the error actually tells developers.

The old error could be read as saying that a rebuilt dependent widget would not see an inherited-widget change. The distinction is that build can read the new value, but initState is called only once for each State object. A value read there is not refreshed by running initState again when dependencies change.

• 01Reworded the ErrorDescription in StatefulElement to explain the one-time State initialization rather than implying that rebuilds cannot see updated inherited values.
• 02Added the same explanation to State.initState documentation, retaining guidance to use didChangeDependencies.
• 03Changed the ExpectFail test helper to pass through the caught error, then asserted the FlutterError type, diagnostic explanation and didChangeDependencies hint.
• 04Changed 2 files, with 29 additions and 13 deletions.

-"its dependent widgets are rebuilt. If the dependent widget's reference to "
-"the inherited widget is in a constructor or an initState() method, "
-"then the rebuilt dependent widget will not reflect the changes in the "
-"inherited widget."

+'its dependent widgets are rebuilt. The framework calls initState() only once for '
+'each State object and does not call it again for those rebuilds, so a value that '
+'initState() reads from an inherited widget is never updated when that inherited '
+'widget changes.'

Review feedback asked for precision about what “once” means and how constructors relate to this assertion. The final wording specifies “for each State object” and focuses on the initState case; the test checks the diagnostic without whitespace normalization.

Merged into flutter/flutter on October 13, 2026 by auto-submit[bot], with merge commit d2e5f21.

An error message should explain the lifecycle rule accurately. This change helps developers distinguish a dependency-triggered rebuild from one-time initialization, without changing framework runtime behavior.

• ▹Describe lifecycle guarantees precisely: once for each State object, not simply once.
• ▹Test the explanation in a diagnostic, not only whether an exception was thrown.