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'

• Lighting is poor. The face landmark model rejects extreme backlight.
• For face capture, the user is off-angle. Pose checks require the face within ~30° of camera-facing.

AuthError('UNAUTHORIZED') on every request

• The token expired or was rejected. Your backend should mint a fresh one; the SDK re-requests it via getToken() on a 401. Confirm your getToken() provider returns a valid, unexpired Keycloak token. See Authentication.
• Wrong backend URL. The token is scoped to a specific environment; a token issued for one environment will not work against another.

NetworkError('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.