Fixing React Native Image Picker Results That Return a content:// URI the Upload Request Can't Read

The Problem

A user picks a photo using an image picker library, the returned URI renders correctly as a preview using <Image source={{ uri }} />, and everything looks fine right up until the actual upload request. On Android specifically — and iOS is rarely affected — the upload either fails silently, throws a generic network or file-not-found error, or uploads a zero-byte file, even though the same code works flawlessly for photos taken directly with the camera. The failure correlates specifically with images picked from Google Photos, a cloud-backed gallery, or certain file providers, not with the picker itself being broken.

Why It Happens

Android's Storage Access Framework can return a content:// URI instead of a real file path

Depending on the source app and Android version, an image picker's result can be a content:// URI — a reference resolved through a content provider — rather than a file:///storage/... path pointing at an actual file on disk. React's Image component can render a content:// URI directly because it goes through Android's own image-loading APIs, but many upload implementations (multipart form data builders, native file-reading code) expect a real filesystem path and don't know how to resolve a content provider reference.

The underlying "file" for a content:// URI might not physically exist as a single local file at all

For cloud-backed sources like Google Photos, the image might not be fully downloaded to local storage — the content provider can stream or generate the bytes on demand when something reads through the proper content-resolver API, without there being a conventional file on disk that a naive file-path-based upload could just open and read.

The preview rendering succeeding creates false confidence that the URI is "just a normal file"

Because <Image source={{ uri: contentUri }} /> renders correctly, it's easy to assume the URI is generically usable and move straight to debugging the upload's network layer — retry logic, headers, server-side validation — when the actual gap is that the upload code was never given a mechanism to correctly read a content-provider-backed URI in the first place.

iOS's equivalent picker generally returns a usable local file path, masking the platform-specific nature of the bug during testing

Developers testing primarily on iOS, or testing on Android only with camera-captured photos (which do return normal file paths), can ship code that appears fully correct because the specific combination that triggers the bug — Android plus a content-provider-backed gallery source — was never actually exercised before release.

The Fix

1. Detect a content:// URI and route it through a proper resolution step before upload

function needsContentResolution(uri) {
  return uri.startsWith("content://");
}

async function resolveUploadableUri(uri) {
  if (!needsContentResolution(uri)) return uri; // already a normal file path
  // Copy the content-resolver-backed data to a real local file first
  const destPath = `${RNFS.CachesDirectoryPath}/upload-${Date.now()}.jpg`;
  await RNFS.copyFile(uri, destPath);
  return `file://${destPath}`;
}

Explicitly checking for the content:// scheme and copying that data to a genuine local file — via a library like react-native-fs that knows how to read through Android's content-resolver mechanism — produces a real file path the upload code can then treat normally, rather than trying to teach every upload call site how to special-case content URIs.

2. Configure the image picker library itself to return a copied local file instead of a raw content URI, if it supports the option

import { launchImageLibrary } from "react-native-image-picker";

launchImageLibrary(
  {
    mediaType: "photo",
    includeBase64: false,
    // Many pickers offer an option to copy the asset to a local temp path
    // rather than returning the raw source URI — check the specific library's docs
  },
  (response) => {
    const localUri = response.assets?.[0]?.uri; // already a usable local file, if configured correctly
  }
);

Several popular image picker libraries can be configured to handle the copy-to-local-file step internally as part of the picking flow, which removes the need for app code to detect and resolve content URIs manually at all — worth checking before building a custom resolution step.

3. Use a multipart upload approach that reads the file stream rather than assuming a plain filesystem path

const formData = new FormData();
formData.append("photo", {
  uri: resolvedUri, // the copied, guaranteed-local file path from step 1
  type: "image/jpeg",
  name: "photo.jpg",
});

fetch(uploadUrl, {
  method: "POST",
  body: formData,
  headers: { "Content-Type": "multipart/form-data" },
});

Once the URI passed into the FormData object is confirmed to be a real, resolved local file path — not a raw content-provider reference — React Native's networking layer can read and stream it normally, which is the same code path that already worked correctly for camera-captured photos.

4. Add explicit error handling and logging around the upload's file-read step to catch this class of failure quickly in the future

try {
  const resolved = await resolveUploadableUri(pickedUri);
  await uploadPhoto(resolved);
} catch (error) {
  console.error("Upload failed, original URI:", pickedUri, error);
  // Distinguishing a resolution failure from a network failure
  // makes this bug class immediately diagnosable from logs alone
}

Logging the original picked URI alongside any upload failure makes the content-provider pattern (content://... appearing in the logs of every failure) immediately visible, turning what would otherwise require reproducing the bug on a specific device and gallery source into something diagnosable directly from error reports.

Why This Works

Each fix addresses a different point in the gap between what an image picker can return and what an upload implementation assumes it receives. Explicit content-URI detection and resolution handles the case regardless of picker library behavior; configuring the picker to copy locally removes the need for that handling in app code entirely, where supported; ensuring the upload only ever receives a resolved local path keeps the existing multipart upload code path unchanged and working; and logging the original URI turns a hard-to-reproduce, device-specific bug into one that's identifiable directly from a stack trace or error log.

Conclusion

An image upload failing only for certain Android gallery sources isn't a network or server-side bug — it's an upload implementation receiving a content:// reference and treating it as if it were a normal file path. Detect and resolve content URIs to a genuine local file before upload, check whether the picker library can handle that copy step internally, ensure the multipart upload only ever receives a confirmed local path, and log the original URI so this specific failure mode is immediately recognizable the next time it surfaces.