Skip to content

Add @awaitNotRequired annotation to flutter sdk#181513

Merged
auto-submit[bot] merged 28 commits into
flutter:masterfrom
victorsanni:unawaited-futures-draft
Apr 25, 2026
Merged

Add @awaitNotRequired annotation to flutter sdk#181513
auto-submit[bot] merged 28 commits into
flutter:masterfrom
victorsanni:unawaited-futures-draft

Conversation

@victorsanni
Copy link
Copy Markdown
Contributor

@victorsanni victorsanni commented Jan 26, 2026

Part of Use @awaitNotRequired in Flutter SDK

Turned on the unawaited_futures lint and added the annotation to every function declared in the flutter SDK and flagged by the linter. This means the annotation is only added to Future-returning functions called at least once without the await keyword preceding it. So if there exists a Future-returning function in the Flutter SDK that does not need to be awaited, but all call sites in the SDK have the await keyword, it is not annotated.

EDIT: Opened PRs to add awaits or ignores to callsites instead of adding the annotation. Some functions may still require this annotation, but this set is much smaller than originally anticipated.

@github-actions github-actions Bot added a: tests "flutter test", flutter_test, or one of our tests a: text input Entering text in a text field or keyboard related problems framework flutter/packages/flutter repository. See also f: labels. labels Jan 26, 2026
@github-actions github-actions Bot added a: animation Animation APIs f: material design flutter/packages/flutter/material repository. a: accessibility Accessibility, e.g. VoiceOver or TalkBack. (aka a11y) f: scrolling Viewports, list views, slivers, etc. f: cupertino flutter/packages/flutter/cupertino repository f: routes Navigator, Router, and related APIs. f: integration_test The flutter/packages/integration_test plugin labels Jan 26, 2026
@github-actions github-actions Bot removed the f: integration_test The flutter/packages/integration_test plugin label Jan 26, 2026
@dkwingsmt
Copy link
Copy Markdown
Contributor

Do we have a plan on the criteria that justify a @awaitNotRequired? It feels like marking parameters optional, and it might be better off reviewed on a case-by-case basis, even better split into separate PRs based on categories of reasons.

@victorsanni
Copy link
Copy Markdown
Contributor Author

Do we have a plan on the criteria that justify a @awaitNotRequired?

There is a lint (unawaited_futures) turned off in the Flutter SDK which basically flags Future-returning function call sites without the await keyword. Is there a scenario where a method flagged by this lint should not have the @awaitNotRequired annotation?

Comment thread packages/flutter/lib/src/widgets/router.dart Outdated
Comment thread packages/flutter/test/material/elevated_button_test.dart
Comment thread packages/flutter/lib/src/painting/image_provider.dart Outdated
Comment thread packages/flutter/lib/src/services/platform_channel.dart
Comment thread packages/flutter/lib/src/services/platform_views.dart Outdated
Comment thread packages/flutter_test/lib/src/goldens.dart
Comment thread packages/flutter_test/lib/src/test_pointer.dart
Comment thread packages/flutter_test/lib/src/test_pointer.dart
Comment thread packages/flutter_test/lib/src/test_text_input.dart Outdated
Comment thread packages/flutter_test/lib/src/widget_tester.dart Outdated
@victorsanni
Copy link
Copy Markdown
Contributor Author

Thanks for the review @dkwingsmt. I didn't think there are situations in the framework where some Future-returning methods do not have a preceding await but should. This is a valid point and makes sense to me.

Is this review exhaustive? i.e are the methods you've pointed out the only ones that should have await added instead of the annotation? Asking because I want to go ahead and open PRs to add await to the ones you have pointed out.

@dkwingsmt
Copy link
Copy Markdown
Contributor

dkwingsmt commented Feb 10, 2026

I didn't review the ones under dev since I'm not as familiar. I went through the other files, although I'm not as confident on some cases such as Navigator. In general my recommendation is that this tag should be used with caution since it's basically ignore-lint that applies to all users.

@victorsanni victorsanni marked this pull request as ready for review February 13, 2026 03:34
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces the @awaitNotRequired annotation across the Flutter SDK to address unawaited_futures lint warnings. The changes are extensive, touching many files to annotate methods that return a Future but are not intended to be awaited, such as animation controllers, navigation methods, and platform channel invocations. This makes the code cleaner and the intent clearer. Additionally, the PR fixes a few instances in tests where tester.pump() was not correctly awaited. The changes are well-executed and improve the overall code quality by adhering to linting best practices.

@victorsanni victorsanni marked this pull request as draft February 13, 2026 22:57
@dkwingsmt
Copy link
Copy Markdown
Contributor

dkwingsmt commented Feb 20, 2026

Related: #182233
In this issue, an error slipped through all try-catch efforts and caused app crash. This was caused by the following structure:

void A() {
  assert(false); // Exception thrown
}

Future<void> animateTo() async {
  A();
}

void handleEvent() { // Sync handler
  animateTo();  // The future is not awaited.
}

void D() {
  try {
    handleEvent(); // D thought this was enough catching.
  } catch {
    FlutterError.report(...);
  }
}

This shows the risk of allowing futures to not be awaited: Async errors will not be caught at all.

Therefore I think we should not allow futures to be un-awaited (except maybe in tests, with discretion). All futures should either be awaited or have a .catch.

_canceled = true;
}

@awaitNotRequired
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should keep the annotation here. This PR added it: #79163? WDYT @dkwingsmt

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I think having no await is the intention here.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

or apply unawaited to the call site

ahmedsameha1 pushed a commit to ahmedsameha1/flutter that referenced this pull request Apr 14, 2026
Fixes flutter#184315
Part of flutter#181513

---------

Co-authored-by: Tong Mu <dkwingsmt@users.noreply.github.com>
mbcorona pushed a commit to mbcorona/flutter that referenced this pull request Apr 15, 2026
Fixes flutter#184315
Part of flutter#181513

---------

Co-authored-by: Tong Mu <dkwingsmt@users.noreply.github.com>
mbcorona pushed a commit to mbcorona/flutter that referenced this pull request Apr 15, 2026
PR: flutter#184042
Revert: flutter#184429
Fixes flutter#184315
Part of flutter#181513

---------

Co-authored-by: Tong Mu <dkwingsmt@users.noreply.github.com>
mbcorona pushed a commit to mbcorona/flutter that referenced this pull request Apr 15, 2026
mbcorona pushed a commit to mbcorona/flutter that referenced this pull request Apr 15, 2026
Part of flutter#181513

---------

Co-authored-by: Tong Mu <dkwingsmt@users.noreply.github.com>
Co-authored-by: Kate Lovett <katelovett@google.com>
mbcorona pushed a commit to mbcorona/flutter that referenced this pull request Apr 15, 2026
@dkwingsmt
Copy link
Copy Markdown
Contributor

This PR is affected by code freeze. I've suggested Victor to split this PR into two parts, landing the non-material/cupertino part while holding the remaining until the freeze is lifted.

@victorsanni victorsanni added CICD Run CI/CD and removed CICD Run CI/CD labels Apr 22, 2026
@victorsanni
Copy link
Copy Markdown
Contributor Author

I moved the code-freezed changes to a separate PR. So this can be merged cleanly.

srawlins
srawlins previously approved these changes Apr 23, 2026
chunhtai
chunhtai previously approved these changes Apr 24, 2026
Copy link
Copy Markdown
Contributor

@chunhtai chunhtai left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, but for internal facing api, we should use unawaited at the call site

_canceled = true;
}

@awaitNotRequired
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

or apply unawaited to the call site

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

a: animation Animation APIs CICD Run CI/CD f: routes Navigator, Router, and related APIs. f: scrolling Viewports, list views, slivers, etc. framework flutter/packages/flutter repository. See also f: labels.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants