Skip to main content
Version: current (0.10)

Troubleshooting

Most integration issues come down to a handful of causes. Work down this page in order — start with the checklist, turn on debug logging, then check the specific sections below.

No events appearing?​

Run through these in order — the first few cover the large majority of cases:

  1. The SDK isn't initialized. If you installed via npm, you must call LuciaSDK.init({ apiKey }) once before any tracking call. If you use the CDN, make sure the script tag has the data-api-key attribute (that's what auto-initializes it). A method called before init throws "LuciaSDK not initialized."
  2. Wrong or placeholder API key. Confirm the key matches the one in your dashboard (Settings → API Keys) — not YOUR_API_KEY.
  3. The page wasn't reloaded. After adding the snippet, hard-refresh the page you're testing (the old page in the tab doesn't have the SDK).
  4. An ad-blocker or privacy extension is blocking it. uBlock, Brave shields, and similar tools can block the script or the event request. Test in a clean browser profile with extensions disabled.
  5. A Content-Security-Policy is blocking it. See Content Security Policy below.
  6. Your site is a single-page app. Pageviews fire on first load; client-side route changes need a manual LuciaSDK.pageView(path) call. See SPA route changes.

Turn on debug logging​

Initialize manually with debug: true to log the SDK's activity to the browser console:

<script src="https://cdn.luciaprotocol.com/lucia-sdk-latest.min.js"></script>
<script>
  LuciaSDK.init({ apiKey: 'YOUR_API_KEY', debug: true });
</script>

With debug on you'll see initialization, each event the SDK sends, and any errors — the fastest way to tell whether the problem is setup (nothing logs) or delivery (it logs but the request fails).

Check the network​

Open your browser's DevTools → Network tab, filter to luciaprotocol, and interact with the page. You should see requests to https://api.luciaprotocol.com returning 200.

  • No request at all → the SDK isn't initialized, or a script/ad-blocker stopped it.
  • Request blocked (CORS/CSP) → see Content Security Policy.
  • Request returns 4xx → usually an invalid API key.

Content Security Policy​

If your site sends a Content-Security-Policy header, the browser will silently refuse to load the SDK or send events unless Lucia's hosts are allowlisted. You'll see console errors like "Refused to load the script…" or "Refused to connect…".

Allow these directives:

script-src  https://cdn.luciaprotocol.com;
connect-src https://api.luciaprotocol.com;
  • script-src — lets the browser load the SDK bundle from the CDN.
  • connect-src — lets the SDK POST events to the Lucia API.
Using the staging/test environment?

If you initialize with testENV: true, events go to https://staging.api.clickinsights.xyz instead — allowlist that host in connect-src for your staging site.

SPA route changes​

The initial pageview is captured on load, but frameworks that change the URL without a full reload (React Router, Vue Router, etc.) need you to record each navigation yourself:

// Call this whenever the route changes
LuciaSDK.pageView(window.location.pathname);

See the Next.js and React guides for framework-specific hooks.

Methods run before init finishes​

LuciaSDK.init() returns a Promise. If you call a method immediately after init in the same tick, await the init first (or rely on CDN auto-init, which the SDK queues correctly):

await LuciaSDK.init({ apiKey: 'YOUR_API_KEY' });
await LuciaSDK.pageView('/home');

Tracking calls are asynchronous and safe to fire-and-forget — a failed event never throws into your UI — but await them if you need to sequence work after the event is sent.

Still stuck?​