prefer_return_await

v0.4.0 Warning Fix Control Flow

Warns when a Future is returned without await inside a try-catch block in an async function. Without await, any exception thrown by the Future will not be caught by the surrounding catch block, silently bypassing your error handling.

Why use this rule

When you write return asyncOp() inside a try-catch, the Future is returned to the caller without being awaited. If asyncOp() throws, the exception propagates to the caller instead of being caught by the local catch block. Adding await ensures the Future completes within the try-catch scope, so exceptions are properly caught and handled.

See also: Asynchronous programming | Dart lint: unnecessary_await_in_return

Don’t

Future<String> badReturnInTry() async {
  try {
    // Exception from asyncOp() won't be caught
    return asyncOp();
  } catch (e) {
    return 'fallback';
  }
}

Future<String> badReturnInCatch() async {
  try {
    throw Exception();
  } catch (e) {
    // Exception from asyncOp() won't be caught
    return asyncOp();
  }
}

Do

Future<String> goodReturnAwaitInTry() async {
  try {
    return await asyncOp();
  } catch (e) {
    return 'fallback';
  }
}

Future<String> goodReturnAwaitInCatch() async {
  try {
    throw Exception();
  } catch (e) {
    return await asyncOp();
  }
}

// Returning Future outside try-catch is fine
Future<String> goodReturnOutsideTryCatch() async {
  return asyncOp();
}

// Non-async function returning Future in try-catch is fine
Future<String> goodNonAsync() {
  try {
    return asyncOp();
  } catch (e) {
    return Future.value('fallback');
  }
}

Configuration

This rule is in the core preset, so it is on with preset: core, preset: recommended or preset: opinionated.

To turn it off:

many_lints.yaml

rules:
  prefer_return_await: false

To keep the rule on but skip certain paths, use per-rule exclude.

Related rules

• avoid_unnecessary_return — Remove a bare return; that ends a void function.
• prefer_early_return — Replace a body-wrapping if with an early-return guard.
• avoid_cascade_after_if_null — Detect cascades after if-null operators without parentheses.
• avoid_collapsible_if — Merge nested if statements with &&.