Skip to main content

Troubleshooting

Feedback or progress is missing​

The production UI options default to hidden. Enable them explicitly:

val style = MBUIOptions.Builder()
    .progressBar(true)
    .faceStatusLabel(true)
    .countdownTimerLabel(true)
    .build()

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 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 or show the face status label. Also confirm that automatic capture is enabled.

Video duration throws an exception​

videoCaptureDuration is measured in milliseconds and must be within 1000..3000:

val options = MBCaptureSessionOptions.Builder()
    .videoCaptureDuration(2_000)
    .build()

Camera does not open​

  • Add the android.permission.CAMERA permission to the manifest.
  • Request runtime camera permission before adding the capture fragment or starting the service.
  • Confirm that no other application or screen is holding the camera.
  • Test camera behavior on a physical device.

Orientation or framing is incorrect​

For a custom V2 or V3 UI, set MBCameraOptions.orientation to the current screen orientation:

val orientation = when (resources.configuration.orientation) {
    Configuration.ORIENTATION_LANDSCAPE -> MBOrientation.LANDSCAPE
    else -> MBOrientation.PORTRAIT
}

Use FIT_CENTER when the entire camera frame must remain visible or FILL_CENTER when the preview should cover the available area.

Session metadata is null​

Set MBCaptureSessionFragment.sessionId before adding the fragment, or pass the ID to startCamera(sessionId) in a custom UI. Metadata also requires device metadata to be available.

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 Android and iOS.