Error Handling

This guide explains how errors surface in the React Native wrapper and how to debug them. Because the wrapper is a thin bridge, errors originate in the native SDKs - the player UI renders an error overlay automatically on both platforms, and the root cause is most often explained by the native error codes.


Where Errors Appear

  1. On-screen error overlay (native): both the Android fragment and the iOS SwiftUI view render a built-in error screen with a Retry button. No app code is required to display it.
  2. Device logs: full error messages, codes, and stack traces go to Logcat (Android) and the Xcode console (iOS).

Until onError is promoted to the public API, the device logs and the on-screen overlay are your primary debugging signal.


Error Categories

Errors fall into a few broad buckets. Each is fully documented in the corresponding native SDK, link through for the authoritative reference.

CategoryTypical CauseReference
Auth / OTPMissing, invalid, or expired OTPAndroid 9102, 9104, 9311, 9312 · iOS license server messages
NetworkNo connectivity, DNS failure, CDN timeoutAndroid 20, 21, 2000–2008 · iOS "init_error_*" messages
DRM / LicenseFairPlay (iOS) or Widevine (Android) license exchange failedAndroid 6000–6008 · iOS "Failed to get CKC: ..."
Device / EnvironmentDeveloper Mode, Simulator, sideloaded installAndroid 9201, 9202, 3201 · iOS: FairPlay is unavailable in Simulator
Media Parsing / DecodingMalformed stream, unsupported codecAndroid 3001–4006
ServerInkrypt backend returned 4xx/5xxAndroid 9101, 9301, 9310, 9320 · iOS: license server messages

Common Scenarios

1. Invalid or Expired OTP

Symptoms: Player shows the error overlay immediately; video never begins loading.

Likely cause: OTPs are short-lived. If the one you passed has already expired or was never valid, the license request fails.

Fix: Generate a fresh OTP from the Inkrypt Dashboard (or your backend) and set a new params object:

setParams({
  videoId: 'YOUR_VIDEO_ID',
  otp: 'NEWLY_GENERATED_OTP',
  autoPlay: true,
});

Note the iOS caveat in Properties: if you've already loaded a video on iOS, you may need to remount the view to apply a new OTP.


2. FairPlay License Failure (iOS)

Symptoms: Loading spinner appears, then the error overlay.

Likely causes

  • Running on the iOS Simulator (FairPlay is hardware-bound and unavailable there)
  • Network issue preventing the license request from reaching Inkrypt's license server
  • Invalid OTP

Fix: Always test on a physical device, verify connectivity, regenerate the OTP.

See: native iOS - Errors Guide → FairPlay License Failure.


3. Developer Mode / USB Debugging Blocked (Android)

Symptoms: Error overlay appears with a message about Developer Options or USB Debugging.

Likely cause:The Android SDK intentionally blocks playback on developer-unlocked devices (error codes 9201 / 9202).

Fix during development: Pass tolerateDeveloperMode: true in params:

setParams({
  videoId,
  otp,
  tolerateDeveloperMode: true, // development only — remove before release
});

Fix for production: Ship without tolerateDeveloperMode and instruct users to disable Developer Options.

See: native Android - Errors Guide → codes 9201/9202.


4. Unsupported Installation (Android)

Symptoms: Error overlay with message about unsupported installation source.

Likely cause: App installed via sideload, not the Play Store (error 3201).

Fix: Distribute through the Play Store. For internal QA, use Play Store internal testing tracks.


5. Network Error During Playback

Symptoms: Playback starts, then stalls and shows an error.

Likely cause: Connection drop, CDN transient failure.

Fix: The on-screen Retry button will re-initialize the session with the same params. No app-side code is required.


Platform-Specific Error References

For the complete error-code tables, use the native docs directly — they are authoritative and stay in sync with native changes:

  • Android: Android - Errors Guide
    • Inkrypt codes: 20, 21, 30, 9101, 9102, 9104, 9201, 9202, 9301, 9310, 9311, 9312, 9320, 3201, 21201
    • Media3 / ExoPlayer codes: 1000–7001+
    • DRM fallback behavior (L3 retry, license retry)
  • iOS: iOS - Errors Guide
    • Common message strings: "init_error_fps_ce", "init_error_video_data", "Failed to get CKC: ...", etc.
    • When errorCode is nil (almost always) vs. the one case where it is set by the license server