Skip to main content

Troubleshooting

Installation​

ErrorFix
npm ERR! ERESOLVE mentioning react or react-nativeYour project uses a React Native or React version that 2.3.3 does not support yet. Use React Native 0.86 or earlier; see Requirements.
npm ERR! 404 or 401 for @mobaibio/mobai-biometricExport MOBAI_ACCESS_TOKEN in the shell that runs npm or Yarn, and check that .npmrc contains @mobaibio:registry.
An older version is installedYour lock file still points to npmjs.com. Run npm install @mobaibio/mobai-biometric@2.3.3.
Unable to find a specification for MobaiBiometric (= 2.3.3)Add the Mobai source line to ios/Podfile and the dl.cloudsmith.io entry to ~/.netrc, then run pod install --repo-update.
Found multiple specifications for MobaiBiometric (2.3.3)Can be ignored. The Mobai source is listed first, so CocoaPods uses it.
Gradle cannot resolve bio.mobai:biometric:2.3.3Check the repository block and token; see Install on Android.

iOS build fails​

  • underlying Objective-C module 'SwiftProtobuf' not found: add use_frameworks! :linkage => :static and the SwiftProtobuf pre_install block from the Quick Start Podfile.
  • The iOS deployment target 'IPHONEOS_DEPLOYMENT_TARGET' is set to 11.0: add the deployment-target loop from the Quick Start Podfile to post_install.

Android build fails​

Error resolving plugin [id: 'com.facebook.react.settings']: build with JDK 17. Set JAVA_HOME, or select JDK 17 under Gradle JDK in Android Studio.

The app closes at launch on iOS 27​

Apps built with the iOS 27 SDK must use the UIScene lifecycle. Follow iOS 27: adopt the UIScene lifecycle.

launch() crashes on iOS​

launch() presents the capture screen from AppDelegate.window. Set window in the AppDelegate, or assign the scene's window to it from your SceneDelegate, as shown in the Quick Start. The custom UI does not use AppDelegate.window.

Feedback or progress is missing​

The predefined UI components default to hidden. Enable them explicitly:

launch({
  showProgressBar: true,
  showFaceStatusLabel: true,
  showCountdownLabel: true,
  cameraPermissionAlert,
});

Debug mode is not required.

Capture remains on "Checking lighting"​

  • Confirm that the full face is visible inside the overlay.
  • Hold the device still while the SDK obtains a fresh measurement.
  • Avoid strong backlight and rapidly changing illumination.
  • Start with MBImageQualityLevel.LEVEL_2 while testing V3 behavior.

The face looks valid but capture does not start​

With V3, geometry can be valid while lighting still fails. Inspect imageQualityStatus in onFaceBoundingBoxValidating, or enable showFaceStatusLabel in the predefined UI.

Camera does not open​

  • Add NSCameraUsageDescription to the iOS Info.plist.
  • On Android, request the CAMERA permission before rendering MBCaptureSessionView; see Custom capture UI.
  • Check that camera access is enabled for the application in the device settings.
  • Test on a physical device.

Session metadata is empty​

  • Pass a sessionId to launch() or setCaptureSessionOptions().
  • On Android, launch() with V1 returns empty metadata. Use V2 or V3, or the custom UI.

The stored image appears different from the preview​

The front-camera preview is intentionally mirrored. Stored images and video are unmirrored so output orientation is consistent across iOS and Android.