Future<T>.error constructor

Future<T>.error(
  1. Object error, [
  2. StackTrace? stackTrace
])

Creates a future that completes with an error.

The created future will be completed with an error in a future microtask. This allows enough time for someone to add an error handler on the future. If an error handler isn't added before the future completes, the error will be considered unhandled.

Use Completer to create a future and complete it later.

Example:

Future<int> getFuture() {
 return Future.error(Exception('Issue'));
}

final error = await getFuture(); // Throws.

Implementation

factory Future.error(Object error, [StackTrace? stackTrace]) {
  // TODO(40614): Remove once non-nullability is sound.
  checkNotNullable(error, "error");
  if (!identical(Zone.current, _rootZone)) {
    AsyncError? replacement = Zone.current.errorCallback(error, stackTrace);
    if (replacement != null) {
      error = replacement.error;
      stackTrace = replacement.stackTrace;
    }
  }
  stackTrace ??= AsyncError.defaultStackTrace(error);
  return new _Future<T>.immediateError(error, stackTrace);
}