Maaz Zindani

Loading the index…

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

A remote image in React Native shows nothing, or only for some URLs

ErrorThe Image takes no space, or an empty box appears where the picture should be

Short answer

A network image in React Native is blank for four reasons. It has no width and height, because remote images are never sized for you. The URL is plain http and the platform blocks it. The file is a format Image cannot decode, such as SVG. The server wants a header such as Authorization. Log onError first.

  • Applies to React Native 0.8x, iOS 17 and later, Android 9 and later
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Give the Image a visible border and a fixed size, and print what the native side reports. onError hands you the error, onLoad tells you the file arrived. Run the app and watch the Metro log: whether you see the failed line, the loaded line, or nothing at all points to one of the causes below.

    <Image
      source={{ uri: url }}
      style={{ width: 200, height: 200, borderWidth: 1 }}
      onError={(e) => console.log('image failed:', url, e.nativeEvent.error)}
      onLoad={() => console.log('image loaded:', url)}
    />
  2. 2Match what you see, then jump to its fix

    1. 1The border from the first step does not appear, or the box has zero height. Neither onLoad nor onError is logged.The image has no width and heightFix
    2. 2onError is logged, and the same file loads once you switch the URL to https.The URL is plain http and the platform blocks itFix
    3. 3onError is logged for one kind of URL only, for example every address ending in .svg, or every .webp on iOS.The file is in a format Image cannot decodeFix
    4. 4The URL opens in a browser where you are signed in, and the app gets a failure. A request without credentials returns 401 or 403.The server wants a header the app does not sendFix

What does the error look like?

  • The Image takes no space, or an empty box appears where the picture should be
  • The same component works with one URL and stays blank with another
  • The image loads on Android and not on iOS, or the reverse

Cause 1 of 4

The image has no width and height

1Check

Look at the style on the Image. A picture from require() is measured at build time, so a local image can go without a size. A remote image is not measured for you, and the React Native docs say so on purpose: you must write the dimensions down.

grep -rn "uri:" src/ | head

2Fix

Put a width and a height in the style of the Image. If the real size is only known later, you can pass width and height inside the source object too, and the docs say they then become the default size.

<Image
  source={{ uri: url }}
  style={{ width: 300, height: 200 }}
/>

3Verify

Reload the app. The bordered box from the first step is now visible and the picture fills it.

npx react-native start

Confirmed by reactnative.dev

Did this fix it?

Cause 2 of 4

The URL is plain http and the platform blocks it

1Check

Open the URL scheme in the failing source. iOS enforces App Transport Security, which wants https. Android blocks cleartext traffic from API level 28 on.

grep -rn "http://" src/
curl -sI https://example.com/photo.jpg | head -n 1

2Fix

Serve the image over https. Only when you cannot, allow that one domain: an NSExceptionDomains entry in Info.plist on iOS, and android:usesCleartextTraffic in the manifest on Android. Avoid switching ATS off for the whole app.

<!-- android/app/src/main/AndroidManifest.xml -->
<application android:usesCleartextTraffic="true" ... >

3Verify

Rebuild the native app, because both settings live in native files, then check that onLoad is logged.

npx react-native run-android

Confirmed by reactnative.dev

Did this fix it?

Cause 3 of 4

The file is in a format Image cannot decode

1Check

Ask the server what it actually sends. The Image docs list the supported formats: png, jpg, jpeg, bmp, gif, webp, and psd on iOS only. They add that webp on iOS works only when it is bundled with the JavaScript code, so a remote webp can fail on iOS and still work on Android.

curl -sI https://example.com/logo.svg | grep -i content-type

2Fix

Ask for a supported format. If you host the file yourself, export it as png or jpg. If a service hosts it, request a png or jpg version of the same picture.

// before: an svg the Image component cannot draw
// after: a png of the same artwork
const url = 'https://example.com/logo.png';

3Verify

The Content-Type header now names a supported type, and onLoad is logged on both platforms.

curl -sI https://example.com/logo.png | grep -i content-type

Confirmed by reactnative.dev

Did this fix it?

Cause 4 of 4

The server wants a header the app does not send

1Check

Request the URL without your credentials and read the status code.

curl -s -o /dev/null -w "%{http_code}\n" https://example.com/private/photo.jpg

2Fix

The source object accepts headers, which are sent along with the request for the remote image. Pass the token there.

<Image
  source={{
    uri: url,
    headers: { Authorization: `Bearer ${token}` },
  }}
  style={{ width: 200, height: 200 }}
/>

3Verify

The same request with the Authorization header returns 200, and onLoad is logged in the app.

curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer $TOKEN" https://example.com/private/photo.jpg

Confirmed by reactnative.dev

Did this fix it?

How do I stop it coming back?

  • Wrap remote images in one small component that always sets a size and an onError fallback, so no screen forgets either.
  • Use https for every image host from the start, including development servers.
  • Serve remote pictures as png or jpg and keep svg and other formats out of an Image.
  • Log onError in development builds so a failing URL names itself in Metro.

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.