Flutter says Unable to load asset for an image or file that exists
Unable 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.
Fix it fast
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 assets2Match what you see, then jump to its fix
- 1
Unable to load asset for a path that exists on diskThe file or folder is not listed under flutter: assets:Fix - 2
unable to find directory entry in pubspec.yaml, or the assets are silently ignoredThe YAML indentation is wrongFix - 3
Works for assets/a.png, fails for assets/icons/a.pngThe file sits in a subfolder that was not declaredFix - 4
Loading icons/heart.png from a dependency failsThe asset belongs to a package and needs the packages/ prefixFix
- 1
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.yaml2Fix
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 runConfirmed by docs.flutter.dev
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 -202Fix
Indent assets: under flutter: and each path under assets:, using spaces (not tabs).
flutter:
uses-material-design: true
assets:
- assets/config.json3Verify
flutter pub get accepts the file without complaint.
flutter pub getConfirmed by docs.flutter.dev
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 d2Fix
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 runConfirmed by docs.flutter.dev
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' lib2Fix
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.png3Verify
The image from the package renders after a full restart.
flutter runConfirmed by docs.flutter.dev
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Qist BazaarA buy-now-pay-later marketplace built from a blank repo, now past 100K downloads on Google Play.
- SessionBirdAn omnichannel engagement suite in Flutter: campaigns, chatbot, tickets, analytics and live calling.
Related fixes
Mobile apps
Flutter Image.network shows nothing or throws when the image fails
EXCEPTION: resolving an image codec
Image.network throws an exception that goes to FlutterError.onError when a download or decode fails, so a 404 leaves a red screen or an empty box.
3 causes, each with a fixMobile apps
Flutter cannot open a file: OS Error No such file or directory
FileSystemException: Cannot open file, path = '...' (OS Error: No such file or directory, errno = 2)
Errno 2 means the exact path you gave does not exist on the device.
3 causes, each with a fixMobile apps
Flutter deep link works while the app is open but not from a closed app
From a fully closed app the link opens only the home screen
On a cold start Flutter does not push the link; it starts the app with an initial route that holds the link path.
3 causes, each with a fixMobile apps
Flutter request fails with SocketException: Failed host lookup
ClientException with SocketException: Failed host lookup
Failed host lookup means the app could not turn the host name into an IP address, so no request was sent.
4 causes, each with a fixMobile apps
image_picker closes the app or returns nothing after choosing a photo
With launchMode singleInstance the picker always returns RESULT_CANCELED
On Android the system can kill MainActivity while the picker is open, so the app restarts and the result never arrives.
3 causes, each with a fixMobile apps
Flutter debug app installs on an iPhone or iPad but the Dart VM never starts
EXC_BAD_ACCESS (SIGKILL - CODESIGNING)
On iOS 14 and later a debug build needs the Local Network permission for the Dart VM service, and it can only be started by Flutter tooling or Xcode, not by tapping its icon.
4 causes, each with a fix