falconGitHub

avoid-catches-without-on-clauses

Same as avoid_catches_without_on_clauses in Dart lints

Group
Style
Path
lint/style/avoid-catches-without-on-clauses
Default
Off, opt in
Origin
Dart lints
Rule
28 of 512

Avoid catch clauses without an on type.

A bare catch (e) swallows everything, including programming errors that should surface. Name the exceptions you can handle:

try { work(); } catch (e) { log(e); } // BAD
try { work(); } on IOException catch (e) { log(e); } // GOOD

A bare catch is allowed when its body hands the caught object on: a rethrow (before any nested catch clause), a throw mentioning it, or passing it to Future.error, Completer.completeError, FlutterError.reportError, Error.throwWithStackTrace, or another call whose resolved return type is Never. A completeError call on a receiver whose type cannot be resolved also counts, so unknown receivers stay silent.

Invalid

example.dartdart
import 'dart:async';

void work() {}
void log(Object e) {}

void bareCatch() {
  try {
    work();
  } catch (e) {
    log(e);
  }
}

void bareCatchWithStack() {
  try {
    work();
  } catch (e, s) {
    log(s);
  }
}

void throwsSomethingElse() {
  try {
    work();
  } catch (e) {
    throw StateError('failed');
  }
}

void rethrowAfterNestedCatch() {
  try {
    work();
  } catch (e) {
    try {
      work();
    } on FormatException {
      log(e);
    }
    rethrow;
  }
}

void ignoresException() {
  try {
    work();
  } catch (e) {
    print('failed');
  }
}

void completesWithOtherError(Completer<void> completer) {
  try {
    work();
  } catch (e) {
    completer.completeError(StateError('other'));
  }
}
Catch clause should use `on` to specify the type of exception being caught.
8 work();
9 } catch (e) {
Catch clause should use `on` to specify the type of exception being caught.
16 work();
17 } catch (e, s) {
Catch clause should use `on` to specify the type of exception being caught.
24 work();
25 } catch (e) {
Catch clause should use `on` to specify the type of exception being caught.
32 work();
33 } catch (e) {
Catch clause should use `on` to specify the type of exception being caught.
45 work();
46 } catch (e) {
Catch clause should use `on` to specify the type of exception being caught.
53 work();
54 } catch (e) {

Valid

example.dartdart
import 'dart:async';

void work() {}
void log(Object e) {}

void withOn() {
  try {
    work();
  } on FormatException catch (e) {
    log(e);
  }
}

void onWithoutCatch() {
  try {
    work();
  } on Exception {
    log('x');
  }
}

void rethrows() {
  try {
    work();
  } catch (e) {
    log(e);
    rethrow;
  }
}

void throwsWrapped() {
  try {
    work();
  } catch (e) {
    throw StateError('wrapped: $e');
  }
}

Future<void> futureError() {
  try {
    work();
    return Future.value();
  } catch (e) {
    return Future.error(e);
  }
}

void completer(Completer<void> completer) {
  try {
    work();
  } catch (e, s) {
    completer.completeError(e, s);
  }
}

void throwWithStack() {
  try {
    work();
  } catch (e, s) {
    Error.throwWithStackTrace(e, s);
  }
}

Never fail(Object error) => throw error;

void neverReturning() {
  try {
    work();
  } catch (e) {
    fail(e);
  }
}

void inferredCompleterInCallback(Stream<int> events) {
  final completed = Completer<Map<String, dynamic>>();
  events.listen((event) async {
    try {
      work();
    } catch (error, stack) {
      // Inferred SDK receivers forward errors just like annotated receivers.
      if (!completed.isCompleted) completed.completeError(error, stack);
    }
  });
}

Configure avoid-catches-without-on-clauses

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

falcon.jsonjson
{
  "linter": {
    "rules": {
      "style": {
        "avoid-catches-without-on-clauses": "error"
      }
    }
  }
}

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

example.dartdart
// falcon-ignore lint/style/avoid-catches-without-on-clauses: <reason>