supapulseAdvancedDebugging
Debugging
Find out why pageviews, events or revenue aren't showing up. Debug mode, the Network tab, error responses and the usual causes.
Checklist
- The site's domain in Supapulse matches the domain of the pages (or is its parent domain).
- The token on the page is the site's public token and starts with
pub_. - The script loads: no 404 or CSP error for
browser.jsin the console. - Requests to
/api/ingestappear in the Network tab and get202. - Nothing blocks them: try a private window without extensions.
1. Turn on debug mode
<script
defer
src="https://cdn.jsdelivr.net/npm/@supapulse/core@1/dist/browser.js"
data-token="YOUR_PUBLIC_TOKEN"
data-debug="true"
></script>Or debug: true in init(). The console then shows:
| Message | Meaning |
|---|---|
[Supapulse] Initialized | init() ran, with the resolved config. |
[Supapulse] Event sent | A pageview or event was handed to the browser. |
[Supapulse] Send failed | The fetch fallback failed; a retry is scheduled. |
[Supapulse] Rate limited, retry after Ns | The API answered 429. |
[Supapulse] Dropped after N attempts | Retries ran out. |
[Supapulse] Not initialized | pageview() or event() was called before init(). |
[Supapulse] Already initialized | init() was called twice on the same instance (harmless). |
2. Check the Network tab
Filter by ingest. Requests sent with sendBeacon show as type ping; the response isn't visible for those, but the request is. A request with status (canceled) during navigation is normal for fetch fallbacks; keepalive still delivers it.
To see the API's answer, send a test request yourself:
curl -i -X POST https://supapulse.app/api/ingest \
-H "Content-Type: application/json" \
-H "X-API-Token: pub_your_token" \
-H "Origin: https://acme.com" \
-d '{"type":"pageview","data":{"url":"https://acme.com/","session_id":"debug-test"}}'A 202 here and a pageview in the dashboard a few seconds later means the token and domain are right, and the problem is in the page.
3. Read the error
| Response | Cause | Fix |
|---|---|---|
401 Missing API token | No token sent | Check data-token or apiToken. |
401 Invalid token format | Token doesn't start with pub_/sec_ | Look for stray quotes or spaces. |
401 Invalid API token | Token regenerated, mistyped, or the site was deleted | Copy it again from the site's settings. |
403 Origin not allowed | Page's domain doesn't match the site | Fix the domain in the site's settings. Subdomains of the site's domain are allowed. |
402 | The site's team has no active plan (plan_inactive), or reached its monthly event limit (quota_exceeded) | Check the team's plan and usage. The tracker doesn't retry a 402. |
422 | Unknown type, missing data, a field that broke a rule, or revenue with a public token | Fix the payload or use the secret token. The response names each field. |
429 | Over 2,000 requests per hour from one IP address | The tracker waits and retries. Common when load testing from one machine. |
net::ERR_BLOCKED_BY_CLIENT | An ad or privacy blocker | Nothing to fix in code. |
4. Content Security Policy
A CSP error in the console names the directive. Allow https://cdn.jsdelivr.net in script-src and https://supapulse.app in connect-src.
5. Single-page apps
- No pageviews after navigation: you set
autoPageviews: falseand don't callpageview(), or your router only changeslocation.hash. See SPA support. - Two pageviews per navigation: your router calls both
pushStateandreplaceState, or you callpageview()with automatic pageviews on.
6. React
useSupapulse must be used within a SupapulseProvider: the component is outside the provider.[Supapulse] Not initializedwarning: an event oridentify()was sent before the provider initialized the tracker, and it was dropped. Send from handlers, or wait forisReady. See hooks.- Next.js:
createContext only works in Client Components: wrap the provider in a'use client'component. See SSR support. - Next.js: token is
undefined: the variable must start withNEXT_PUBLIC_, and you must rebuild after changing it.
7. Revenue
202but no new revenue: a payment with the sametransaction_idandevent_typewas already stored.- Revenue shows as direct: Supapulse found no visit for the customer. Call
identify()with the same ID you send ascustomer_id, and do it within the site's salt rotation window (1 to 30 days) of the visit. - Stripe revenue missing: check the last-event time in the site's settings. If it's empty, Stripe isn't reaching the endpoint; see the Stripe guide.
402: the site's team has no active plan.422: a field failed validation (the response names it), or the public token was used. Revenue needs the secret token.
8. Still stuck
Email support@supapulse.app with:
- the page URL and the site's domain as set in Supapulse;
- the console output with debug mode on;
- the status and response body of a failing
/api/ingestrequest; - for revenue, the
transaction_idand when you sent it.
Never send the secret token.