Skip to main content

Troubleshooting

Feedback or progress is missing​

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

let style = MBUIOptions(
    showProgressBar: true,
    showFaceStatusLabel: true,
    showCountdownTimerLabel: true
)

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 .level2 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 is unexpected​

videoCaptureDuration is measured in milliseconds and is clamped to 1000...3000:

let options = MBCaptureSessionOptions(videoCaptureDuration: 2_000)

Camera does not open​

  • Add NSCameraUsageDescription to Info.plist.
  • Check that camera access is enabled for the application in iOS Settings.
  • Test camera behavior on a physical device.
  • Stop the capture view when its screen disappears.

Orientation or framing is incorrect​

  • Enable the required orientations on the application target.
  • Keep the capture view constrained to the visible view bounds.
  • Use .fit when the entire camera frame must remain visible or .fill when the preview should cover the available area.

Session metadata is nil​

Pass a sessionId into MBCaptureSessionViewController or onStartCapturing(sessionId:). 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 iOS and Android.