Add @awaitNotRequired annotation to flutter sdk by victorsanni · Pull Request #181513 · flutter/flutter

victorsanni · 2026-01-26T21:37:14Z

Draft to fix 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.

Missing annotation:
integrationDriver :

flutter/packages/integration_test/lib/integration_test_driver_extended.dart

Line 77 in 2c74ab1

Future<void> integrationDriver({

Because this will require incurring a dependency on package:meta/meta.dart in package:integration_test/integration_test_driver.dart.

dkwingsmt · 2026-02-10T20:50:21Z

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 · 2026-02-10T20:58:05Z

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?

dkwingsmt · 2026-02-10T21:10:53Z

packages/flutter/lib/src/widgets/router.dart

  }

+  @awaitNotRequired
  Future<void> _rebuild([void value]) {


It seems like the returned future of this private method is never used. Why can't it simply return void?

True, i think it was initially added as a Future<void> to satisfy the .then API, but no longer needed to after #100657.

packages/flutter/test/material/elevated_button_test.dart

packages/flutter/lib/src/painting/image_provider.dart

dkwingsmt · 2026-02-10T21:37:08Z

packages/flutter/lib/src/services/platform_channel.dart

  /// Returns a [Future] which completes to the received response, which may
  /// be null.
+  @awaitNotRequired
  Future<T?> send(T message) async {


Should we really mark send and invokeMethod as awaitNotRequired? IMO these foundational methods should require await and let individual usages suppress the warning explicitly.

I agree, there are other callsites in the framework with await. Should we suppress the warning with an ignore or add awaits?

I suspect many such usages are intentional, probably because those send do not wait for responses. For such cases it's ok to explicitly ignore while commenting that it's intentional to not wait for response. LMK if there are other cases that you're unsure of.

packages/flutter/lib/src/services/platform_views.dart

dkwingsmt · 2026-02-10T21:45:12Z

packages/flutter_test/lib/src/goldens.dart

  /// The method by which [golden] is located and by which its bytes are written
  /// is left up to the implementation class.
+  @awaitNotRequired
  Future<void> update(Uri golden, Uint8List imageBytes);


I feel like this should enforce await. Can you check where it is used?

Agree, most of its callsites use await, its non-await callsites are primarily from this test file in this PR: #160484.

I can go ahead and add await to these callsites.

packages/flutter_test/lib/src/test_pointer.dart

packages/flutter_test/lib/src/test_text_input.dart

packages/flutter_test/lib/src/widget_tester.dart

victorsanni · 2026-02-10T22:58:20Z

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 · 2026-02-10T23:10:52Z

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.

gemini-code-assist

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.

…-draft

dkwingsmt · 2026-02-20T00:27:06Z

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.

victorsanni · 2026-02-14T01:24:01Z

dev/benchmarks/macrobenchmarks/lib/src/web/bench_mouse_region_grid_hover.dart

  }

+  @awaitNotRequired
  Future<void> start() async {


Hi @dkwingsmt, I see you added this method (and its other clones below) in #59803, did you intend to use it in the postFrameCallback without await?

I think awaitNotRequired is ok here, since this is only used in a fully managed test that I expect no errors to occur, and I'm ok with errors being thrown.

victorsanni · 2026-02-14T01:38:06Z

dev/benchmarks/macrobenchmarks/lib/src/animation_with_microtasks.dart

    _canceled = true;
  }

+  @awaitNotRequired


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

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

Impl: ```dart /// Sends the specified [message] to the platform plugins on this channel. /// /// Returns a [Future] which completes to the received response, which may /// be null. Future<T?> send(T message) async { return codec.decodeMessage(await binaryMessenger.send(name, codec.encodeMessage(message))); } ``` Part of #181513

Part of #181513

Part of [Add @awaitNotRequired annotation to flutter sdk](#181513)

Impl: ```dart /// Sends the specified [message] to the platform plugins on this channel. /// /// Returns a [Future] which completes to the received response, which may /// be null. Future<T?> send(T message) async { return codec.decodeMessage(await binaryMessenger.send(name, codec.encodeMessage(message))); } ``` Part of flutter#181513

Part of flutter#181513

…er#183334) Part of [Add @awaitNotRequired annotation to flutter sdk](flutter#181513)

Part of [Add @awaitNotRequired annotation to flutter sdk](#181513)

victorsanni · 2026-03-12T00:58:37Z

packages/flutter/lib/src/animation/animation_controller.dart

  /// which switches to [AnimationStatus.completed] when [upperBound] is
  /// reached at the end of the animation.
+  @awaitNotRequired
  TickerFuture forward({double? from}) {


Add comment to TickerFuture impl:

A TickerFuture should probably NOT be awaited at all, since it is risky to hang forever. Instead, people who wish to know when/whether it completes will explicitly attach a callback anyway. This should make it reasonable to make mark all TickerFuture as awaitNotRequired.

Part of [Add @awaitNotRequired annotation to flutter sdk](#181513)

Add @awaitNotRequired annotation to flutter sdk

0fcce5e

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

Merge branch 'master' into unawaited-futures-draft

987fe55

victorsanni added 2 commits January 26, 2026 14:07

Fix linux analyze

2bd4fc4

Fix web tests

6f653de

github-actions bot removed the f: integration_test The flutter/packages/integration_test plugin label Jan 26, 2026

Merge branch 'master' into unawaited-futures-draft

9ad391a

dkwingsmt reviewed Feb 10, 2026

View reviewed changes

Piinks mentioned this pull request Feb 12, 2026

Use @awaitNotRequired in Flutter SDK #168555

Open

victorsanni added 2 commits February 12, 2026 19:18

Apply review suggestions

1ae760e

Merge branch 'flutter:master' into unawaited-futures-draft

9d75327

victorsanni marked this pull request as ready for review February 13, 2026 03:34

gemini-code-assist bot reviewed Feb 13, 2026

View reviewed changes

Merge branch 'flutter:unawaited-futures-draft' into unawaited-futures…

90a3ccc

…-draft

victorsanni marked this pull request as draft February 13, 2026 22:57

victorsanni commented Feb 24, 2026

View reviewed changes

This was referenced Feb 27, 2026

Add await to flutter_test callsites #182983

Merged

Add await to callsites of BasicMessageChannel.send #182868

Merged

Add await or ignore lint to invokeMethod callsites #182870

Open

Ignore unawaited_futures lint in dev/automated_tests #182922

Merged

github-merge-queue bot pushed a commit that referenced this pull request Mar 5, 2026

Add await to flutter_test callsites (#182983)

b0eae2a

Part of #181513

victorsanni mentioned this pull request Mar 6, 2026

Add await or ignore lint to flutter_driver unawaited callsites #183334

Merged

github-merge-queue bot pushed a commit that referenced this pull request Mar 9, 2026

Add await or ignore lint to flutter_driver unawaited callsites (#183334)

1e02e10

Part of [Add @awaitNotRequired annotation to flutter sdk](#181513)

victorsanni mentioned this pull request Mar 9, 2026

Add await to more flutter/flutter callsites #183413

Merged

xxxOVALxxx pushed a commit to xxxOVALxxx/flutter that referenced this pull request Mar 10, 2026

Add await to flutter_test callsites (flutter#182983)

fff6b46

Part of flutter#181513

xxxOVALxxx pushed a commit to xxxOVALxxx/flutter that referenced this pull request Mar 10, 2026

Add await or ignore lint to flutter_driver unawaited callsites (flutt…

6a77fd3

…er#183334) Part of [Add @awaitNotRequired annotation to flutter sdk](flutter#181513)

This was referenced Mar 10, 2026

Add awaits to dev/ callsites #183479

Merged

Add await to more flutter/test callsites #183486

Closed

Add awaits to flutter/test callsites #183487

Merged

victorsanni added 3 commits March 11, 2026 10:36

Remove annotation where no longer needed

5273a07

Merge branch 'master' into unawaited-futures-draft

71f2663

More removals

ce8e082

victorsanni requested a review from dkwingsmt March 11, 2026 17:55

github-merge-queue bot pushed a commit that referenced this pull request Mar 11, 2026

Add awaits to dev/ callsites (#183479)

fd89d20

Part of [Add @awaitNotRequired annotation to flutter sdk](#181513)

victorsanni commented Mar 12, 2026

View reviewed changes

github-merge-queue bot pushed a commit that referenced this pull request Mar 13, 2026

Add await to more flutter/flutter callsites (#183413)

c777faa

Part of [Add @awaitNotRequired annotation to flutter sdk](#181513)

github-merge-queue bot pushed a commit that referenced this pull request Mar 13, 2026

Add awaits to flutter/test callsites (#183487)

41bc812

Part of [Add @awaitNotRequired annotation to flutter sdk](#181513)

Merge branch 'master' into unawaited-futures-draft

bdeed06

victorsanni added the CICD Run CI/CD label Mar 13, 2026

Conversation

victorsanni commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dkwingsmt commented Feb 10, 2026

Uh oh!

victorsanni commented Feb 10, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dkwingsmt Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

victorsanni commented Feb 10, 2026

Uh oh!

dkwingsmt commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

dkwingsmt commented Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

victorsanni commented Jan 26, 2026 •

edited

Loading

dkwingsmt Feb 13, 2026 •

edited

Loading

dkwingsmt commented Feb 10, 2026 •

edited

Loading

dkwingsmt commented Feb 20, 2026 •

edited

Loading