[fahaddoc]

When dependOnInheritedWidgetOfExactType() is called before initState() has completed, the error explains the rule like this:

When an inherited widget changes, for example if the value of Theme.of() changes, 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.

That last sentence is easy to read as saying the rebuild itself does not see the change, which is what the issue reports as confusing. The rebuild does see it: a widget that depends on an inherited widget is rebuilt when that inherited widget changes, and a build() method that reads it gets the new value. What is never updated is whatever initState() read, because the framework calls initState() only once for each State object and does not call it again for those rebuilds.

This replaces that sentence with the actual reason, and adds the same reason to State.initState's documentation, which told readers not to call dependOnInheritedWidgetOfExactType() there but not why. The ErrorHint that points at build() and didChangeDependencies() is unchanged.

After:

When an inherited widget changes, for example if the value of Theme.of() changes, 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.

The existing test for this error (initState() dependency on Inherited asserts) only checks that something was thrown, so the message itself was untested; the new test covers it. ExpectFail now forwards the caught error so a test can inspect it.

The issue also suggests adding a _StateLifecycle value between created and initialized, set just before initState() is called. I left that out. A State only gets its context after it is constructed (state._element is assigned in the StatefulElement constructor after createState() returns), so the only State code that runs with a context before initState() completes is initState() itself, and a new value would have no constructor case to separate. That is also why the new message no longer mentions constructors; the general advice about constructors stays in the BuildContext.dependOnInheritedWidgetOfExactType docs.

Fixes #105705

Pre-launch Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the AI contribution guidelines and understand my responsibilities, or I am not using AI tools.
• I read the Tree Hygiene wiki page, which explains my responsibilities.
• I read and followed the Flutter Style Guide, including Features we expect every widget to implement.
• I signed the CLA.
• I listed at least one issue that this PR fixes in the description above.
• I updated/added relevant in-code documentation (doc comments with ///).
• If this PR introduces a new feature or capability, I created and linked a website documentation issue or PR in flutter/website (or verified none is needed).
• I added new tests to check the change I am making, or this PR is test-exempt.
• I followed the breaking change policy and added Data Driven Fixes where supported.
• All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel on Discord.

If this change needs to override an active code freeze, provide a comment explaining why. The code freeze workflow can be overridden by code reviewers. See pinned issues for any active code freezes with guidance.

Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the gemini-code-assist bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.

[gemini-code-assist]

Code Review

This pull request updates the documentation and error messages in 'framework.dart' to clarify that 'initState' is called only once per 'State' object and is not re-run when an inherited widget changes, meaning values read within it are never updated. It also updates 'inherited_test.dart' to include a regression test verifying that the error message thrown when accessing an inherited widget in 'initState' correctly explains this behavior. There are no review comments, and thus no feedback is provided.

[victorsanni]

Hi, please remember to re-request a review when you have made changes to your PRs, so it can re-enter my review queue. Else I don't see that your PR has been updated and can't leave a review.

[fluttergithubbot]

An existing Git SHA, 3dc747c833300d80998cbe571e8bc88560afad46, was detected, and no actions were taken.

To re-trigger presubmits after closing or re-opeing a PR, or pushing a HEAD commit (i.e. with --force) that already was pushed before, push a blank commit (git commit --allow-empty -m "Trigger Build") or rebase to continue.

[victorsanni]

LGTM with nits.

[Renzo-Olivares]

LGTM modulo @victorsanni comments.

[fahaddoc]

@victorsanni Thanks for the re-review. Two things left on this one, neither of which I can do from my side.

Google testing is failing on 8a4866e (go/frob_pr/192727, completed earlier today). I can't see the run, so flagging it rather than guessing. One thing worth checking first: this PR changes the ErrorDescription text in the dependOnInheritedElement assertion, so an internal test asserting on the old wording would explain it:

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.

If that is what it is, I'm happy to adjust the new wording to whatever keeps the internal tests working, or the test can be updated on your side — whichever you prefer.

The CICD label came off when I pushed the test fold, so Awaiting CICD label is stuck pending. Could you re-add it? Everything else is green.

[Renzo-Olivares]

LGTM