Skip to Content
OperationsTroubleshooting

Troubleshooting

Camera won’t open

  • Confirm the page is on HTTPS, localhost, or 127.0.0.1. Plain HTTP blocks getUserMedia.
  • Check site permissions in the browser. Permanent denial requires the user to clear them.
  • On Safari iOS, ensure the page is the active tab. Background tabs pause the stream.

Capture loops endlessly in 'detecting'

  • The user is too close or too far. Default proximity ranges are tight; widen via proximityRange. See Tune capture quality.
  • Lighting is poor. The face landmark model rejects extreme backlight; the hand landmark model needs enough contrast to find finger contours.
  • For face capture, the user is off-angle. Pose checks require the face within ~30° of camera-facing.

'degraded' event fires on fingerprint capture

The SDK could not load its full quality-scoring stack and fell back to a coarser scorer. Captures still succeed; scores are less precise.

  • Check your CSP. wasm-unsafe-eval (CSP level 3) or unsafe-eval (older browsers) is required for the full scoring path.
  • For local development, set forceQualityFallback: true to use the coarse scorer deliberately.
  • If this persists in production, contact your Slade ID integration contact.

AuthError('UNAUTHORIZED') on every request

  • ClientSecret expired. Issue a fresh one server-side and retry.
  • Wrong backend URL. The token is scoped to a specific environment; a token issued for one environment will not work against another.

NetworkError('REQUEST_TIMEOUT') intermittently

The server is slow, the user’s network is, or both. Bump timeoutMs from the default 15 seconds. Do not raise it past 60 seconds — users will abandon the flow before then.

Faces fail anti-spoof reliably for one user

  • Extreme backlight. The model interprets silhouette-on-bright as a screen replay. Move to even lighting.
  • Camera quality. Very low-resolution webcams (under 480p) often fail anti-spoof regardless of who is in front. Confirm the device’s actual capture resolution.

Per-finger quality fails after a slap

  • The hand is rotated. The cropper assumes fingers point roughly upward. Rotate the device, not the hand.
  • One finger is in shadow. NFIQ2 scores ridges, and shadowed ridges look like noise. Re-frame to even out lighting across the slap.
  • The user is pressing flat against the camera. Contactless fingerprint capture works best at the documented proximity range; too close blurs ridges.
Telemetry and privacy