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
- 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.
- 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.
| Category | Typical Cause | Reference |
|---|---|---|
| Auth / OTP | Missing, invalid, or expired OTP | Android 9102, 9104, 9311, 9312 · iOS license server messages |
| Network | No connectivity, DNS failure, CDN timeout | Android 20, 21, 2000–2008 · iOS "init_error_*" messages |
| DRM / License | FairPlay (iOS) or Widevine (Android) license exchange failed | Android 6000–6008 · iOS "Failed to get CKC: ..." |
| Device / Environment | Developer Mode, Simulator, sideloaded install | Android 9201, 9202, 3201 · iOS: FairPlay is unavailable in Simulator |
| Media Parsing / Decoding | Malformed stream, unsupported codec | Android 3001–4006 |
| Server | Inkrypt backend returned 4xx/5xx | Android 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)
- Inkrypt codes:
- iOS: iOS - Errors Guide
- Common message strings:
"init_error_fps_ce","init_error_video_data","Failed to get CKC: ...", etc. - When
errorCodeisnil(almost always) vs. the one case where it is set by the license server
- Common message strings: