Troubleshooting

Common issues, organized by symptom.

No events in the dashboard

Check 1: SDK actually loaded

Open DevTools → Network tab → reload the page. Look for:

sdk.galacha.me/sdk/latest/galacha.umd.js  → 200

Check 2: Init actually fired

Enable debug mode:

<GalachaProvider projectKey="..." debug>

Console should show:

[galacha/react] booting {sdkUrl: '...', projectKey: '4d4b83bcd00a…'}
[galacha/react] script injected https://sdk.galacha.me/sdk/latest/galacha.umd.js
[galacha/react] script onload
[galacha/react] init called. isReady: true

Check 3: Events POST

Network tab → filter by api.galacha.me. Within 5s of interacting with the page, you should see:

POST api.galacha.me/api/v1/events  → 200

Sessions appear but anonymous visitors don't

Expected behavior. Sessions without identify() still record but show up as "anonymous" in the dashboard. Filter settings may hide them — check:

1. Sessions page → top right → Show anonymous toggle
2. Or filter by: user_identifier IS NULL

If you truly want no anonymous recording, check the identifier on the Provider:

<GalachaProvider projectKey="..." identifier={user?.id} />

Without a user, the Provider still boots but you can gate recording on user existence by using disabled:

<GalachaProvider projectKey="..." disabled={!user}>

useGalacha must be used inside <GalachaProvider>

You called useGalacha() in a component that isn't a descendant of <GalachaProvider>. Wrap a common ancestor — usually your root layout.

// app/layout.tsx
<GalachaProvider projectKey="...">
  {children}   // ← useGalacha() works here and below
</GalachaProvider>

Next.js hydration warning

Caused by env vars mismatching between server and client build. Verify:

• NEXT_PUBLIC_GALACHA_PROJECT_KEY is set in .env.local (dev) and Vercel env (prod)
• You're reading it via process.env.NEXT_PUBLIC_GALACHA_PROJECT_KEY, not a runtime fetch
• You're NOT reading it inside a server component without the NEXT_PUBLIC_ prefix

Intermittent capture (sometimes events, sometimes not)

Typically means:

1. React StrictMode double-invoke edge case — fixed in @galacha/react >= 0.1.2. Upgrade.
2. stop() called on logout — Galacha.stop() tears down the recorder. Until a page reload, no more events. Remove the stop call from your logout handler.
3. Unmounting/remounting the Provider — if your Provider lives inside a conditional route that unmounts, boot state persists but context state can flicker. Move the Provider higher.

Session shows DOM but no clicks

Your Provider has captureClicks: false. Remove it (default is true).

Network panel is empty in replay

Your Provider has captureNetwork: false, OR your HTTP library bypasses fetch/XHR (e.g., native bridge). Verify:

<GalachaProvider projectKey="..." captureNetwork />

Test by calling fetch("https://httpbin.org/get") from a button and checking the dashboard.

Password fields visible

Impossible on web — password inputs are always masked at the recorder level. If you're seeing a password value, it's actually a type="text" input styled to look like a password. Change to type="password".

Too many events, buffer warnings in console

Your app is logging excessively (captureConsole) or emitting a lot of mousemove events. Mitigations:

<GalachaProvider
  projectKey="..."
  captureConsole={false}        // drop console capture
  flushIntervalMs={2000}        // flush more frequently
  flushMaxEvents={25}           // force flush sooner
/>

CSP blocks the script

Strict Content-Security-Policy. Add to your CSP:

script-src 'self' https://sdk.galacha.me;
connect-src 'self' https://api.galacha.me;

If you can't whitelist the CDN, email kelvin@galacha.me for a self-hosted bundle.

React Native: TouchCaptureView throws

Either:

• Galacha.init() hasn't been called yet — move the init call into a mount effect before the wrapper renders
• Galacha.getBuffer() returned null — add the ! assertion: buffer={Galacha.getBuffer()!}

React Native: upgraded SDK, new features missing

You forgot to rebuild the native binary. JS reloads don't pick up Kotlin/Swift changes. Run:

npx expo prebuild
npx expo run:android   # or run:ios

Still stuck

Email kelvin@galacha.me with:

• Your project ID
• A screenshot of the DevTools Network tab showing SDK + events requests
• Console output with debug mode enabled
• Framework + version (e.g., "Next.js 15 App Router")

Related

• Configuration
• GalachaProvider
• How it works