Troubleshooting

Things not working? Start here. These are the most common issues people run into.

Events not showing in the dashboard

Check your project ID. Open your browser console and look for network requests to /api/v1/event. If you see 400 errors, your data-id attribute probably has a typo.

<!-- Make sure this matches your actual project ID from Settings -->
<script src="https://cdn.jsdelivr.net/npm/@vibeping/sdk@latest/dist/vibeping.umd.js"
  data-id="vp_your_actual_project_id">
</script>

Check the API response. Open DevTools → Network tab, filter by "event". Click a request and check the response body. A 200 means it went through. A 400 means the payload was rejected (bad project ID or malformed data). A 429 means you hit the rate limit — wait a minute.

Are you on localhost? The SDK works on localhost, but make sure your dashboard API is reachable.

Ad blockers. Some ad blockers flag analytics scripts. If you're testing with uBlock Origin or similar, try disabling it temporarily. In production, most users don't block first-party analytics — and VibePing's privacy-first approach means fewer blockers target it compared to Google Analytics.

SDK not initializing

If window.__vibeping is undefined after the script loads:

Check script loading order. The VibePing script must finish loading before you call any methods. If you're using the CDN script tag, place it in <head> — it loads async by default.
Check for JavaScript errors. Open the browser console. If there's a syntax error in your own code that fires before VibePing loads, it can block execution.
npm import issues. If you installed via npm, make sure you're calling init():

import { init } from '@vibeping/sdk';
 
init({ id: 'vp_your_project_id' });

Without init(), nothing gets tracked.

SPA route changes not tracked

VibePing auto-detects single-page app navigation by listening to popstate events and patching pushState/replaceState. This works with React Router, Next.js App Router, Vue Router, and most SPA frameworks out of the box.

If route changes aren't being tracked:

Hash-based routing (/#/about) — VibePing tracks these via hashchange events. Make sure you're on SDK v0.1.0 or later.
Custom router — If your framework uses a non-standard navigation method, you can manually track page views:

import { track } from '@vibeping/sdk';
 
track('pageview', { url: window.location.pathname });

CORS errors

If you see Access to fetch has been blocked by CORS policy in the console, check what URL the SDK is sending events to. The hosted dashboard at app.vibeping.dev accepts requests from any origin.

Duplicate events

Seeing double page views or events? Common causes:

React Strict Mode runs effects twice in development. This is expected — it won't happen in production builds.
Multiple script tags. Check your HTML — make sure you only have one VibePing script tag. If you added it via both a <script> tag and an npm import, pick one.
Hot module replacement (HMR). During development, HMR can re-run initialization code. This is normal and doesn't affect production.

Web Vitals not appearing

Web Vitals (LCP, CLS, INP, TTFB) are only measured on real page loads — not on client-side navigations in SPAs.

LCP and INP require the page to finish rendering and (for INP) a user interaction. If you're testing by just opening a page and immediately checking the dashboard, give it a few seconds and interact with the page. Note: FID was deprecated in March 2024 and replaced by INP — debug INP instead.
Development mode can skew Vitals significantly. Always check production numbers.
CLS accumulates over the page lifetime. It might take a few seconds of scrolling and interacting before the final value is sent.

Rate limiting (429 errors)

The hosted API has rate limits to prevent abuse:

Endpoint	Limit
Event ingestion	60 requests/minute per IP
Stats API	30 requests/minute per IP
Uptime API	10 requests/minute per IP

If you're hitting limits during development, you're probably refreshing too aggressively. In production, the SDK batches events automatically — you shouldn't hit these limits under normal usage.

Still stuck?

Contact support with your browser console output and SDK version. We respond fast.