Media SDK

Appearance

Native troubleshooting ​

Common issues when integrating @media-sdk/native and @media-sdk/ui-native.

useMediaClient must be used inside a MediaProvider ​

Cause: A hook was called outside the MediaProvider tree.

Fix: Wrap your app (or the screen subtree) with MediaProvider and pass a MediaClient:

tsx
<MediaProvider client={client}>
  <YourScreens />
</MediaProvider>

Network request failed / fetch is not defined ​

Cause: React Native version below 0.71, or a test environment without fetch.

Fix:

  • Use react-native ≥ 0.71 (global fetch required by @media-sdk/core).
  • In tests, polyfill global.fetch (see packages/media-core transport tests).

@media-sdk/ui-native lists react-native >= 0.71 as a peer dependency for this reason.

AbortError / cancelled requests showing as errors ​

Cause: Custom search code not using isAbortError.

Fix: Hooks swallow abort errors automatically. For custom client.searchPhotos calls, use isAbortError from @media-sdk/core:

ts
import { isAbortError } from "@media-sdk/core";

try {
  await client.searchPhotos({ query, signal });
} catch (error) {
  if (isAbortError(error)) return;
  throw error;
}

Core 0.3.1 adds createAbortError() for RN-safe abort detection.

UNSUPPORTED_FILTER or UNSUPPORTED_CAPABILITY ​

Cause: Filter or operation not supported by the active provider.

Fix: Gate UI with useMediaCapabilities. See the provider matrix.

tsx
// Don't pass size filter on Pixabay
photoFilters: caps.photoFilters.size ? { size: "large" } : undefined

API key / 401 errors ​

Cause: Missing or invalid API key.

Fix:

  • Expo: use EXPO_PUBLIC_* prefix and restart the dev server after changing .env.
  • Verify the key works with a direct curl to the provider API.
  • Never commit .env — use .env.example for placeholders.

Metro cannot resolve @media-sdk/* ​

Cause: Monorepo symlinks or stale cache.

Fix:

bash
npx expo start -c
# or
npx react-native start --reset-cache

For monorepo development, ensure workspace packages are built (pnpm build) before running the example.

Images not loading ​

Cause: Invalid URI, ATS (iOS), or cleartext HTTP blocked.

Fix: Pexels and Pixabay serve HTTPS URLs — ensure photo.src fields are populated. Check device network connectivity.

Video does not play in VideoPreview ​

Expected: @media-sdk/ui-native does not bundle a video player.

Fix: Pass renderVideo with your preferred player (expo-av, react-native-video):

tsx
<VideoPreview
  video={video}
  onClose={close}
  renderVideo={(_v, src) =>
    src ? <YourPlayer uri={src} /> : null
  }
/>

Type errors with workspace packages ​

Cause: Importing from packages/*/src instead of published dist/.

Fix: Import from package names only:

ts
import { useMediaSearch } from "@media-sdk/native";
import { PhotoGrid } from "@media-sdk/ui-native";

Run pnpm verify:starter-native to validate tarball installs in a clean consumer.

verify:starter-native fails ​

Cause: Unbuilt packages or version mismatch.

Fix:

bash
pnpm --filter @media-sdk/core build
pnpm --filter @media-sdk/native build
pnpm --filter @media-sdk/ui-native build
pnpm verify:starter-native