Skip to Content
Web SDKOperationsTroubleshooting

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.

ERR_PNPM_FETCH_401 when installing the SDK

[ERR_PNPM_FETCH_401] GET https://npmjs.slade360.co.ke/@sladeid%2Fslade-id-sdk: Unauthorized - 401
No authorization header was set for the request.

“No authorization header was set” is the tell: pnpm did not send a credential at all, rather than sending a rejected one.

The usual cause is a registry token — or a ${SLADEID_TOKEN} reference to one — sitting in the project .npmrc. pnpm deliberately refuses to expand environment variables in credentials read from a committed file, skips the line with a warning, and continues unauthenticated. Move the credential to user-level config:

pnpm config set "//npmjs.slade360.co.ke/:_authToken" <your-token>

and leave the project .npmrc holding only @sladeid:registry=https://npmjs.slade360.co.ke/. Full explanation, including why the broken form survives review, is in Prerequisites → Private registry access.

Two things that mask the problem, in case it “works on your machine”: npm expands the variable and authenticates fine, and pnpm serves the package from a warm content-addressable store without contacting the registry at all. It fails only on a genuinely clean machine.

A 401 that does say a token was used is a different problem — the token is wrong, revoked, or scoped to another registry. Ask your Slade ID contact to reissue it.

Telemetry and privacyVersioning