Maaz Zindani

Loading the index…

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

Flutter says Unable to load asset for an image or file that exists

ErrorUnable to load asset: "assets/images/logo.png".

Short answer

Flutter only bundles files that pubspec.yaml lists. The error means the path in your code has no matching entry there. Check the YAML indentation, add the folder with a trailing slash, remember that subfolders are not included, and add the packages/ prefix for files that live in a dependency.

  • Applies to Flutter 3.3x stable, Dart 3.x, Android, iOS, web
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Compare the exact string in your code with the assets section of pubspec.yaml. Paths are relative to the project root and are case sensitive.

    sed -n '/^flutter:/,$p' pubspec.yaml
    ls -R assets
  2. 2Match what you see, then jump to its fix

    1. 1Unable to load asset for a path that exists on diskThe file or folder is not listed under flutter: assets:Fix
    2. 2unable to find directory entry in pubspec.yaml, or the assets are silently ignoredThe YAML indentation is wrongFix
    3. 3Works for assets/a.png, fails for assets/icons/a.pngThe file sits in a subfolder that was not declaredFix
    4. 4Loading icons/heart.png from a dependency failsThe asset belongs to a package and needs the packages/ prefixFix

What does the error look like?

  • Unable to load asset: "assets/images/logo.png".
  • The asset does not exist or has empty data.
  • Error: unable to find directory entry in pubspec.yaml

Cause 1 of 4

The file or folder is not listed under flutter: assets:

1Check

Only files named in pubspec.yaml are bundled. A folder entry needs a trailing slash.

grep -n -A8 '^flutter:' pubspec.yaml

2Fix

Add the file, or its folder with a trailing slash, then stop the app and run it again so the bundle is rebuilt.

flutter:
  assets:
    - assets/images/

3Verify

The widget that failed now shows the image.

flutter run

Confirmed by docs.flutter.dev

Did this fix it?

Cause 2 of 4

The YAML indentation is wrong

1Check

assets: must sit two spaces under flutter:, and each list item under assets:. A flush-left assets: line is a common slip.

sed -n '/^flutter:/,$p' pubspec.yaml | cat -A | head -20

2Fix

Indent assets: under flutter: and each path under assets:, using spaces (not tabs).

flutter:
  uses-material-design: true
  assets:
    - assets/config.json

3Verify

flutter pub get accepts the file without complaint.

flutter pub get

Confirmed by docs.flutter.dev

Did this fix it?

Cause 3 of 4

The file sits in a subfolder that was not declared

1Check

A folder entry bundles only the files directly inside it. Subfolders are skipped, except resolution variants such as 2.0x/.

find assets -type d

2Fix

Add one line for every subfolder you load from.

flutter:
  assets:
    - assets/
    - assets/icons/
    - assets/data/

3Verify

Load a file from each subfolder once.

flutter run

Confirmed by docs.flutter.dev

Did this fix it?

Cause 4 of 4

The asset belongs to a package and needs the packages/ prefix

1Check

Assets from a dependency are addressed with the package name, not as plain app paths.

grep -rn 'AssetImage' lib

2Fix

Pass the package name to AssetImage. For files the dependency did not list itself, name them in your app's pubspec.yaml with packages/<package>/ in front and without lib/.

const AssetImage('icons/heart.png', package: 'my_icons');

# pubspec.yaml, for an unlisted file
flutter:
  assets:
    - packages/fancy_backgrounds/backgrounds/background1.png

3Verify

The image from the package renders after a full restart.

flutter run

Confirmed by docs.flutter.dev

Did this fix it?

How do I stop it coming back?

  • Keep assets in one top-level folder and list each subfolder explicitly in pubspec.yaml.
  • Use consistent lowercase file names, since lookups are case sensitive.
  • After changing the assets list, stop the app and start it again instead of relying on hot reload.
  • Load paths from constants so a typo shows up in one place.

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.