Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

Dart error: The argument type 'Future<File>' can't be assigned to the parameter type 'File'

ErrorThe argument type 'Future<File>' can't be assigned to the parameter type 'File'.

Short answer

A Future<File> is a promise of a file, not the file itself. Wherever a plain File is needed, wait for the future first: put await in an async function, or let a FutureBuilder hand you the value when it completes. Creating the future inside build causes a second problem, so start it in initState.

  • Applies to Dart 3.x, Flutter 3.3x stable, null safety on
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find the call that produces the future and read its declared return type in the analyzer message or by hovering. Every function marked async returns a Future, so a call to it gives a Future even if the body returns a plain File.

    dart analyze lib/
  2. 2Match what you see, then jump to its fix

    1. 1The error sits on a line that calls your own helper, and the helper is declared Future<File>The call is missing await inside an async functionFix
    2. 2The call sits in build(), a constructor argument or a field initializer, where await is not allowedYou are in a place that cannot be async, such as a widget's build methodFix

What does the error look like?

  • The argument type 'Future<File>' can't be assigned to the parameter type 'File'.

Cause 1 of 2

The call is missing await inside an async function

1Check

Dart's guide says await unwraps a future and works only inside an async function. Without it you hold an uncompleted future, which prints as Instance of '_Future<...>'.

grep -n 'Future<File>' -r lib/

2Fix

Mark the calling function async and put await before the call. Do not change the helper's return type to File: an async function always returns a Future.

Future<void> save() async {
  final File file = await createLocalFile('notes.txt');
  await upload(file);
}

3Verify

Analysis is clean and the file value is a real File at that line.

dart analyze lib/

Confirmed by dart.dev

Did this fix it?

Cause 2 of 2

You are in a place that cannot be async, such as a widget's build method

1Check

build must return a widget at once, so it cannot wait. Flutter's FutureBuilder is meant for this: it shows its state until the future completes, then gives you snapshot.data.

grep -n 'FutureBuilder' -r lib/

2Fix

Start the future once in initState, keep it in a field, and read the finished file in the builder. The FutureBuilder docs warn that the future must not be created during build, because each rebuild would start the work again.

late final Future<File> _fileFuture;

@override
void initState() {
  super.initState();
  _fileFuture = createLocalFile('notes.txt');
}

@override
Widget build(BuildContext context) {
  return FutureBuilder<File>(
    future: _fileFuture,
    builder: (context, snapshot) {
      if (!snapshot.hasData) return const CircularProgressIndicator();
      return Text(snapshot.data!.path);
    },
  );
}

3Verify

The screen shows a progress indicator first, then the data, and the error is gone.

flutter analyze

Confirmed by api.flutter.dev

Did this fix it?

How do I stop it coming back?

  • Name async helpers so the reader expects a future, for example loadFile, and keep Future in their return type.
  • Turn on the discarded_futures lint in analysis_options.yaml, as Dart's guide suggests.
  • Create futures in initState or a controller, never inside build.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.