Set data-log-level="debug" (script tag) or logLevel: 'debug' in initialize options to see the SDK's internal [MotiSig] console logs while debugging.

SDK not initialized

MotiSig web SDK not initialized

initialize either hasn't run or returned false (empty sdkKey / projectId).

Verify both data-sdk-key and data-project-id (or initialize options) are present and non-empty.
For the script tag, calls made before load must use the command-queue loader or wait for window.motisig.

Events not sending

Most mutating calls require a current user.

event() works anonymously, but tags/attributes/updateUser/getUser require identify first.
If you see no current user, call identify(userId) after auth succeeds.
Confirm the network request to POST /events (or /users) is reaching your configured base URL.

`window.motisig` is undefined

The async script hasn't loaded yet.

Use the command-queue loader so early calls are queued and replayed.
In auth callbacks, poll with waitForMotisig() before calling identify.
Check the browser network tab for a blocked or 404 script request.

FingerprintJS blocked

If you enable FingerprintJS (data-fingerprint="true" or anonymous: { optOut: false }), the SDK loads it lazily from a third-party CDN, which ad blockers or a strict CSP may block.

The SDK falls back to an internal crypto.randomUUID() id when the CDN load fails.
By default FingerprintJS is not loaded; use internal UUID only unless you opt in.
For CSP, allow the FingerprintJS CDN origin or supply your own id via anonymous.getVisitorId.

Duplicate user on identify

Calling identify for an existing user returns HTTP 409, which the SDK treats as success — this is expected on every login and is not an error.

CORS / origin not allowed (403 from Client API)

Browser requests from the web SDK are checked against your project's allowed web domains list. Native iOS, Android, and Expo SDKs send no browser headers (Origin / Sec-Fetch-* / Referer) and skip this check entirely.

Common 403 responses:

"Web SDK access is not configured. Add at least one allowed web domain in project API key settings." — the allowlist is empty, so all browser calls fail closed. Add at least one origin under Settings → API Keys → SDK → Allowed web domains and save.
"Origin is not allowed for this project" — a domain is configured, but the request's origin is not on the list.

How the check works

The server resolves the request origin from the Origin header, falling back to Referer if Origin is absent.
Matching is an exact string compare after normalizing to scheme + host + port. There are no wildcards or subdomain patterns — https://app.example.com does not cover https://www.example.com or https://preview.example.com. List each origin you serve from.
CORS preflight (OPTIONS) always reflects the Origin and returns 204, so a passing preflight does not mean your origin is allowed. Enforcement happens on the real GET/POST, which is where the 403 appears.

Fix checklist

In the MotiSig app, open Settings → API Keys → SDK and add your site's origin (see Allowed web domains).
In DevTools → Network, open the failing Client API request (not the OPTIONS preflight) and copy the Origin request header — it must match a saved entry exactly (scheme, host, and port).
For local dev, add http://localhost:3000 (or your port) — it is not added automatically. Only http://localhost and http://127.0.0.1 may use http; every other origin must be https.
Watch for common mismatches: www vs apex domain, http vs https, an explicit non-default port, staging hostname vs production allowlist, and preview URLs (for example each *.vercel.app deploy) needing their own entry since wildcards are not supported.
If a CORS error shows in the console but no 403 reaches your code, confirm the request actually hit the Client API base URL (not a stale/blocked host) and that you are not sending custom request headers — only Content-Type, X-API-Key, and X-Project-ID are allowed cross-origin.

Wrong environment / base URL

Events appear in the wrong project or not at all.

Production defaults to https://api.motisig.ai/client.
For dev/staging, set data-base-url or baseURL to your dev client API host.

Troubleshooting