Maaz Zindani

Loading the index…

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

Flutter Image.network shows nothing or throws when the image fails

ErrorEXCEPTION: resolving an image codec

Short 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.

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

Fix it fast

  1. 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 5
  2. 2Match what you see, then jump to its fix

    1. 1Only 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. 2Every 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. 3The URL opens in a browser and answers 200, but the image codec exception appears.The file is not an image format Flutter decodesFix

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 | head

2Fix

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 run

Confirmed by api.flutter.dev

Did this fix it?

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/*.entitlements

2Fix

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 --release

Confirmed by docs.flutter.dev

Did this fix it?

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-type

2Fix

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 20

3Verify

The first bytes are binary image data, not text starting with <.

curl -sI https://example.com/photo.jpg | grep -i content-type

Confirmed by api.flutter.dev

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

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