Troubleshooting
Most problems show up as a console warning on localhost. Start there.
No events at all
- Does the project ask for consent first, or did the visitor opt out? With "Ask for consent first" on, nothing is sent before
datacub.consent.grant(). A visitor who calleddatacub.consent.revoke()stays opted out on that browser. Onlocalhostthe SDK warnsno consent yet. - Is the key right? It starts with
pk_live_orpk_test_followed by 24 to 48 letters and digits. The placeholderpk_live_YOUR_PROJECT_KEYis refused:init: bad key. - Is your site allowed? Check Where data may come from in Settings, General.
localhostworks only with apk_test_key. In the browser's network tab, a403from/v1/batchwithorigin_not_allowedmeans the site is not on the list. - Is Global Privacy Control on? Browsers with GPC count as an opt-out. See consent.
- Is an ad blocker dropping the request? Use a first-party proxy.
Then use Check the connection in Settings, Integrations: it waits for your next event and says when it lands.
Warnings and what they mean
| Warning | Fix |
|---|---|
init: bad key | use a real pk_ key; apiHost must be https (or http://localhost) |
refused a secret key. Use a pk_ key. | never put an sk_ key in client code |
bad name | event names cannot start with $ or look like IDs. See names |
bad id | the ID looks like an email, phone, national ID or placeholder. Send your internal user ID |
no consent yet | only with "Ask for consent first" on: expected until your consent flow grants |
In React Native the same checks print as track: invalid event name, identify: ID refused, init: expected a pk_live_ or pk_test_ key, and init: no app id when app is missing.
Responses from datacub
| Status | Meaning | What the SDK does |
|---|---|---|
401 invalid_key | the key does not exist or was revoked | stops for this page or launch |
403 origin_not_allowed, 403 app_not_allowed | the site or app is not on the allowed list | stops for this page or launch |
403 project_suspended, 403 project_in_review | the project is paused | stops for this page or launch |
403 ingestion_paused | the trial ended without a plan (billing) | stops for this page or launch |
429 rate_limited | too many events at once | retries after the time datacub asks for |
5xx or offline | datacub or the network is down | retries with backoff, keeps up to 1,000 events |
Page views are missing or doubled
- Only the first page counts in a single page app: your router may use the URL fragment. Set
hashRouting: true. - A page counts twice:
initis called with two different setups, or the script tag and the npm package are both loaded. Load the SDK once. - Paths show
:idor:redacted: that is on purpose. IDs and personal data are removed from URLs.
Users look duplicated or merged
- One person shows as many users: call
identifyafter every login, on every device. Safari users who stay away for 7 days return as new Guests until they sign in. - Two people show as one: call
reset()at logout.
Mobile
- Nothing survives a restart: pass
storagetoinit. - Events from Expo Go are refused: Expo Go works only with a
pk_test_key. - Nothing sent in tests:
await datacub.flush()before the test ends.