Flutter Image.network shows nothing or throws when the image fails
EXCEPTION: resolving an image codecShort answer
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. Add an errorBuilder to show a fallback. If every image fails, check the Android INTERNET permission, the macOS network entitlement and the file format.
Fix it fast
1Find out which cause you have
Open the image URL in a normal browser. A 404 or an HTML page means the URL is the problem; a picture means the app is the problem.
curl -sI https://example.com/photo.jpg | head -n 52Match what you see, then jump to its fix
- 1
Only some images fail, and the log shows a status code such as 404.The URL is wrong or returns an error, and nothing handles itFix - 2
Every network image fails on a real build, often only on Android release or on a macOS app.The app has no permission to use the networkFix - 3
The URL opens in a browser and answers 200, but the image codec exception appears.The file is not an image format Flutter decodesFix
- 1
What does the error look like?
EXCEPTION: resolving an image codec
Cause 1 of 3
The URL is wrong or returns an error, and nothing handles it
1Check
Flutter reports image loading exceptions to FlutterError.onError unless you give an errorBuilder. Check whether your Image.network has one.
grep -rn "Image.network" lib | head2Fix
Pass an errorBuilder that returns a placeholder. Return a plain widget there so the layout keeps its size.
Image.network(
url,
errorBuilder: (context, error, stackTrace) {
return const SizedBox(
width: 80,
height: 80,
child: Icon(Icons.broken_image),
);
},
)3Verify
Point the widget at a URL you know is missing. The placeholder shows and no red error appears.
flutter runConfirmed by api.flutter.dev
Cause 2 of 3
The app has no permission to use the network
1Check
The Flutter networking guide says an Android app needs the INTERNET permission, and a macOS app needs the network client entitlement in both entitlements files.
grep -n "INTERNET" android/app/src/main/AndroidManifest.xml
grep -n "network.client" macos/Runner/*.entitlements2Fix
Add the permission to the main AndroidManifest.xml, and the entitlement to DebugProfile.entitlements and Release.entitlements on macOS.
<!-- android/app/src/main/AndroidManifest.xml -->
<uses-permission android:name="android.permission.INTERNET" />
<!-- macos/Runner/*.entitlements -->
<key>com.apple.security.network.client</key>
<true/>3Verify
Do a full rebuild, not a hot reload, and run a release build.
flutter clean && flutter run --releaseConfirmed by docs.flutter.dev
Cause 3 of 3
The file is not an image format Flutter decodes
1Check
Image supports JPEG, PNG, GIF, animated GIF, WebP, animated WebP, BMP and WBMP, and tries platform decoding for others. SVG and an HTML error page are not decoded. Check the content type.
curl -sI https://example.com/photo.jpg | grep -i content-type2Fix
Serve one of the supported formats, or use a package that renders the format you have (for SVG, an SVG package). If the server returns an HTML page with status 200, fix the server.
curl -s https://example.com/photo.jpg | head -c 203Verify
The first bytes are binary image data, not text starting with <.
curl -sI https://example.com/photo.jpg | grep -i content-typeConfirmed by api.flutter.dev
How do I stop it coming back?
- Give every Image.network an errorBuilder, and a loadingBuilder for slow connections.
- Keep image URLs in one place so a bad one is fixed once.
- Test one broken URL on purpose before a release.
- On the web, read the CORS page if the same image works on mobile but fails in the browser.
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 web request fails with a CORS error and Dart code cannot fix it
CORS preflight channel did not succeed
In a browser, the browser decides whether your Dart code may read a cross-origin response, and the server grants that with CORS headers.
4 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 says Unable to load asset for an image or file that exists
The asset does not exist or has empty data.
Flutter only bundles files that pubspec.yaml lists.
4 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 fix