avoid_ futureor_ void
Don't use the type 'FutureOr
Description
#
The analyzer produces this diagnostic when the type
FutureOr<void>
is used as the type of a result (to be precise: it is used in a
position that isn't contravariant). The type
FutureOr<void>
is
problematic because it may appear to encode that a result is either a
Future<void>
, or the result should be discarded (when it is
void
). However, there is no safe way to detect whether we have one
or the other case because an expression of type
void
can evaluate
to any object whatsoever, including a future of any type.
It is also conceptually unsound to have a type whose meaning is something like "ignore this object; also, take a look because it might be a future".
An exception is made for contravariant occurrences of the type
FutureOr<void>
(e.g., for the type of a formal parameter), and no
warning is emitted for these occurrences. The reason for this
exception is that the type does not describe a result, it describes a
constraint on a value provided by others. Similarly, an exception is
made for type alias declarations, because they may well be used in a
contravariant position (e.g., as the type of a formal
parameter). Hence, in type alias declarations, only the type
parameter bounds are checked.
Example
#import 'dart:async';
FutureOr<void> m() => null;
Common fixes
#
A replacement for the type
FutureOr<void>
which is often useful is
Future<void>?
. This type encodes that a result is either a
Future<void>
or it is null, and there is no ambiguity at run time
since no object can have both types.
It may not always be possible to use the type
Future<void>?
as a
replacement for the type
FutureOr<void>
, because the latter is a
supertype of all types, and the former is not. In this case it may be a
useful remedy to replace
FutureOr<void>
by the type
void
.
Unless stated otherwise, the documentation on this site reflects Dart 3.9.2. Page last updated on 2025-9-1. View source or report an issue.