falconGitHub

unawaited-futures

Same as unawaited_futures in Dart lints

Group
Style
Path
lint/style/unawaited-futures
Default
On (recommended)
Origin
Dart lints
Rule
446 of 512
recommended

Future results in async bodies must be awaited or marked unawaited.

Forgetting await inside an async function lets the caller continue before the work finishes and drops its errors:

Future<void> save() async {
  writeFile(); // BAD
  await writeFile(); // GOOD
  unawaited(writeFile()); // GOOD: explicitly fire-and-forget
}

Expression statements, cascade sections, and string interpolations whose resolved type is Future (or a subtype) or FutureOr are reported inside async and async* bodies. Assignments, Future.delayed(duration, computation), Map.putIfAbsent, and members annotated @awaitNotRequired in this file are exempt; nullable or unresolved types stay silent.

Invalid

example.dartdart
import 'dart:async';

Future<int> fetch() async => 1;

FutureOr<int> maybeFetch() => 1;

class Api {
  Future<void> save() async {}

  Future<int> get pending async => 1;
}

Future<void> callsFunction() async {
  fetch();
}

Future<void> callsMethod(Api api) async {
  api.save();
}

Future<void> readsGetter(Api api) async {
  api.pending;
}

Future<void> cascade(Api api) async {
  api..save();
}

Stream<int> generator() async* {
  fetch();
  yield 1;
}

void syncWithAsyncClosure() {
  final callback = () async {
    fetch();
  };
  callback();
}
Add an `await` for the `Future` computed by this expression.
13Future<void> callsFunction() async {
14 fetch();
Add an `await` for the `Future` computed by this expression.
17Future<void> callsMethod(Api api) async {
18 api.save();
Add an `await` for the `Future` computed by this expression.
21Future<void> readsGetter(Api api) async {
22 api.pending;
Add an `await` for the `Future` computed by this expression.
25Future<void> cascade(Api api) async {
26 api..save();
Add an `await` for the `Future` computed by this expression.
29Stream<int> generator() async* {
30 fetch();
Add an `await` for the `Future` computed by this expression.
35 final callback = () async {
36 fetch();

Valid

example.dartdart
import 'dart:async';
import 'package:meta/meta.dart' show awaitNotRequired;
import 'package:meta/meta.dart' as meta;

Future<int> fetch() async => 1;

class Api {
  Future<void> save() async {}
}

void syncBody() {
  fetch();
}

Future<void> awaited() async {
  await fetch();
}

Future<void> marked() async {
  unawaited(fetch());
}

Future<void> assigned() async {
  final future = fetch();
  await future;
}

Future<int> returned() async {
  return fetch();
}

Future<void> delayed() async {
  Future.delayed(Duration.zero, () => 1);
}

Future<void> putIfAbsent(Map<String, Future<int>> cache) async {
  cache.putIfAbsent('key', fetch);
}

Future<void> assignment(Api api) async {
  Future<void> pending;
  pending = api.save();
  await pending;
}

FutureOr<int> maybeFetchOr() => 1;

// Like the official rule, `FutureOr` results are not reported in async bodies.
Future<void> callsFutureOr() async {
  maybeFetchOr();
}

Future<void> annotatedLocalFunctions() async {
  @awaitNotRequired
  Future<void> handleError() async {}
  handleError();
  print('${handleError()}');

  @meta.awaitNotRequired
  Future<void> prefixed() async {}
  prefixed();
}

Configure unawaited-futures

Set its severity in falcon.json. See the configuration guide.

falcon.jsonjson
{
  "linter": {
    "rules": {
      "style": {
        "unawaited-futures": "error"
      }
    }
  }
}

Or silence one occurrence with a suppression comment; the reason is required.

example.dartdart
// falcon-ignore lint/style/unawaited-futures: <reason>
  • unintended-html-in-doc-commentunintended_html_in_doc_commentrecommended

    Flags angle-bracket text in doc comments that Markdown would render as an HTML tag.

  • unnecessary-await-in-returnunnecessary_await_in_return

    Avoid await on a returned Future the function's own Future already covers.

  • unnecessary-brace-in-string-interpsunnecessary_brace_in_string_interpsrecommended

    Flags ${x} string interpolations whose braces can be dropped.

  • unnecessary-breaksunnecessary_breaksrecommended

    Flags a trailing break in a switch case that already ends implicitly.

  • unnecessary-constructor-nameunnecessary_constructor_namerecommended

    Flags a redundant .new on constructor declarations and invocations.

  • unnecessary-finalunnecessary_final

    Don't use final for local variables and parameters.

  • unnecessary-lateunnecessary_laterecommended

    Flags a redundant late modifier on an initialized static or top-level variable.

  • unnecessary-library-directiveunnecessary_library_directiverecommended

    Flags a library directive that has neither a doc comment nor annotations.