Troubleshooting

Events not appearing

If you’re not seeing events in your Databuddy dashboard, work through these checks:

Verify the tracker is loaded

Check that the Databuddy script is present on your page:

import { isTrackerAvailable } from '@databuddy/sdk';

if (isTrackerAvailable()) {
  console.log('Databuddy tracker is loaded');
} else {
  console.error('Databuddy tracker is not available');
}

Or check in browser console:

console.log(window.databuddy); // Should show tracker object
console.log(window.db);        // Alternative shorthand

If undefined, the script hasn’t loaded. Check:

Network tab for script loading errors
Content Security Policy (CSP) blocking the script
Ad blockers interfering with the script

Enable debug mode

Turn on debug logging to see what’s happening:

import { Databuddy } from '@databuddy/sdk/react';

<Databuddy debug />

This will log:

Event tracking calls
Batching behavior
Network requests
Errors

Check your browser console for Databuddy logs.

Check client ID configuration

Verify your client ID is set correctly:

// Check environment variable
console.log(process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID);

// Or pass explicitly
<Databuddy clientId="your-client-id-here" />

Your client ID should be:

A valid UUID format
Matching the ID from your Databuddy dashboard
Prefixed with NEXT_PUBLIC_ in Next.js to make it available in the browser

Verify API endpoint

Ensure events can reach the Databuddy API:

Open browser DevTools → Network tab
Filter by “basket.databuddy.cc”
Trigger an event (navigate to a page)
Look for POST requests to /v1/batch or /v1/event

If requests are:

Blocked by CORS: Check your domain is allowed in Databuddy settings
404 errors: Verify your API URL and client ID are correct
401/403 errors: Check your client ID and permissions
Not appearing: The tracker may not be loaded or events aren’t firing

Check event batching

Events are batched by default. They send after:

10 events collected (default batch size)
2 seconds elapsed (default batch timeout)
Page unload/navigation

Force immediate sending for testing:

import { track, flush } from '@databuddy/sdk';

track('test_event', { test: true });
flush(); // Force immediate send

Or disable batching entirely:

<Databuddy enableBatching={false} />

Verify you're not in bot detection

Databuddy automatically filters bot traffic. If you’re testing in:

Headless browsers
Automated testing tools
Some dev tools

You may be flagged as a bot. Disable bot detection for testing:

<Databuddy ignoreBotDetection />

Performance issues

Script blocking page load

The Databuddy script is designed to be non-blocking, but if you’re experiencing issues:Next.js:

import { Databuddy } from '@databuddy/sdk/react';

// The component automatically uses next/script with afterInteractive
<Databuddy />

Other frameworks:

<script src="https://cdn.databuddy.cc/databuddy.js" async defer></script>

Use async or defer to prevent blocking.

Too many network requests

If you see excessive requests:

Increase batch size:

<Databuddy batchSize={20} batchTimeout={5000} />

Reduce tracking volume:
- Don’t track every mouse movement
- Debounce rapid events
- Use sampling for high-frequency events

Enable sampling:

<Databuddy samplingRate={0.1} /> {/* Track 10% of events */}

Large event payloads

Keep event properties lean:Bad:

track('page_loaded', {
  entire_dom: document.body.innerHTML,  // Too large!
  all_styles: getAllComputedStyles(),   // Unnecessary
  full_state: JSON.stringify(appState)  // Too much data
});

Good:

track('page_loaded', {
  page_type: 'product',
  load_time_ms: 1250,
  interactive: true
});

Properties should be:

Primitives (strings, numbers, booleans)
Small arrays or objects
Under 1KB per event

Tracking accuracy

Session tracking issues

Sessions reset after 30 minutes of inactivity. If you’re seeing unexpected session behavior:Get current session ID:

import { getSessionId } from '@databuddy/sdk';

const sessionId = getSessionId();
console.log('Current session:', sessionId);

Clear session for testing:

import { clear } from '@databuddy/sdk';

clear(); // Generates new session and anonymous IDs

Sessions are stored in sessionStorage and cleared when:

Browser tab is closed
30 minutes of inactivity pass
clear() is called

User tracking across domains

To track users across multiple domains:

import { getTrackingParams } from '@databuddy/sdk';

// When linking to another domain
const params = getTrackingParams();
const url = `https://other-domain.com?${params}`;

// Link: https://other-domain.com?anonId=xxx&sessionId=yyy

On the destination domain, Databuddy will automatically detect and use these IDs.

Duplicate events

If you’re seeing duplicate events:

Check for double tracking:

// Bad: Multiple Databuddy components
<Databuddy />
<Databuddy /> {/* Remove duplicate */}

Avoid tracking in useEffect without dependencies:

// Bad: Tracks on every render
useEffect(() => {
  track('component_rendered');
});

// Good: Track only once on mount
useEffect(() => {
  track('component_mounted');
}, []);

Debounce rapid events:

import { useDebouncedCallback } from 'use-debounce';

const trackSearch = useDebouncedCallback((query) => {
  track('search_performed', { query });
}, 500);

Events missing properties

If event properties aren’t appearing:

Check property types:

// Only JSON-serializable types work
track('event', {
  valid_string: 'hello',
  valid_number: 42,
  valid_boolean: true,
  valid_null: null,
  invalid_function: () => {}, // Removed
  invalid_undefined: undefined, // Removed
  invalid_symbol: Symbol(),     // Removed
});

Verify property names:
- Use snake_case or camelCase
- Avoid special characters
- Don’t start with numbers

Check for circular references:

const obj = { name: 'test' };
obj.self = obj; // Circular reference - will fail

track('event', { data: obj }); // Error

Integration issues

Next.js App Router issues

If tracking isn’t working in Next.js App Router:

Ensure client component:

'use client'; // Must be at the top

import { track } from '@databuddy/sdk';

Add Databuddy to root layout:

app/layout.tsx

import { Databuddy } from '@databuddy/sdk/react';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <Databuddy />
        {children}
      </body>
    </html>
  );
}

Check environment variables are exposed:

.env.local

# Must start with NEXT_PUBLIC_ to be available in browser
NEXT_PUBLIC_DATABUDDY_CLIENT_ID=your-client-id

Server-side tracking not working

The browser SDK doesn’t work on the server. For server-side tracking, use the Node SDK:

import { Databuddy } from '@databuddy/sdk/node';

const client = new Databuddy({
  apiKey: process.env.DATABUDDY_API_KEY,
  websiteId: process.env.DATABUDDY_WEBSITE_ID,
});

await client.track({
  name: 'server_event',
  properties: { source: 'api' }
});

Note:

Use API key (not client ID) for server-side
Events won’t have session/anonymous IDs unless you pass them explicitly

Webpack/bundler errors

If you get bundler errors:

Module not found: Can't resolve '@databuddy/sdk'

Reinstall dependencies:

rm -rf node_modules package-lock.json
npm install

Check import path:

// Correct imports
import { track } from '@databuddy/sdk';           // Browser tracking
import { Databuddy } from '@databuddy/sdk/react'; // React component
import { Databuddy } from '@databuddy/sdk/node';  // Node.js SDK

Ensure package is installed:
```
npm list @databuddy/sdk
```

TypeScript errors

If you’re getting TypeScript errors:

Missing types:
```
npm install --save-dev @types/node
```

Type errors in track():

import { track } from '@databuddy/sdk';

// Type-safe tracking
track('purchase', {
  amount: 99.99,
  currency: 'USD',
  // TypeScript will validate property types
});

Module resolution:

tsconfig.json

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "esModuleInterop": true
  }
}

Webhook issues

For webhook troubleshooting, see the webhooks guide.

Data discrepancies

Metrics don't match Google Analytics

Databuddy and Google Analytics may show different numbers due to:

Bot filtering: Databuddy filters bots by default, GA may not
Sampling: GA samples data on high traffic, Databuddy never samples
Session definitions: Different session timeout configurations
Client-side filtering: Ad blockers block GA more aggressively
Timing: GA has delayed reporting, Databuddy is real-time

Expect 5-15% variance, which is normal and often means Databuddy is more accurate.

Revenue numbers don't match Stripe

Check:

Webhook configuration: Ensure webhooks are set up correctly
Metadata: Verify you’re passing Databuddy IDs in Stripe metadata
Currency conversion: All amounts should be in cents (Stripe) vs dollars (display)
Refunds: Check if refunds are being tracked separately
Test mode: Ensure you’re not mixing test and live mode data

Time zone differences

Databuddy stores all timestamps in UTC. Your dashboard may show different times based on:

Your browser’s time zone
Dashboard time zone settings
Query time zone parameters

When comparing with other systems, ensure you’re using the same time zone.

Getting help

If you’re still experiencing issues:

Check the documentation

Review:

Enable debug mode

<Databuddy debug />

Check browser console for detailed logs and error messages.

Test with minimal setup

Create a simple test page with only Databuddy:

import { Databuddy } from '@databuddy/sdk/react';
import { track } from '@databuddy/sdk';

export default function Test() {
  return (
    <div>
      <Databuddy debug />
      <button onClick={() => track('test_click')}>
        Test Event
      </button>
    </div>
  );
}

If this works, the issue is likely in your implementation.

Check service status

Visit status.databuddy.cc to see if there are any ongoing issues.

Contact support

Reach out with:

Description of the issue
Steps to reproduce
Browser/framework versions
Console logs (with debug mode enabled)
Network tab screenshots

Email: support@databuddy.cc

Common error messages

Error	Cause	Solution
`Invalid client ID`	Client ID is malformed or missing	Verify your client ID is a valid UUID
`CORS error`	Domain not allowed	Add your domain in Databuddy settings
`Rate limit exceeded`	Too many requests	Increase batch size or reduce event volume
`Webhook signature invalid`	Wrong webhook secret	Update webhook secret in settings
`Failed to send event`	Network error	Check API endpoint and connectivity
`Tracker not available`	Script didn’t load	Check for ad blockers, CSP, or script errors

Next steps

API Reference

Full SDK documentation and API details

Custom Dashboards

Build custom analytics and reports

Webhooks

Set up payment and event webhooks

Migration Guide

Switch from Google Analytics

Get Started

Core Concepts

SDK Integration

Tracking

Features

Privacy & Compliance

Self-Hosting

Guides

Events not appearing

Performance issues

Tracking accuracy

Integration issues

Webhook issues

Data discrepancies

Getting help

Common error messages

Next steps

API Reference

Custom Dashboards

Webhooks

Migration Guide

Build docs developers (and LLMs) love

Get Started

Core Concepts

SDK Integration

Tracking

Features

Privacy & Compliance

Self-Hosting

Guides

Documentation Index

​Events not appearing

​Performance issues

​Tracking accuracy

​Integration issues

​Webhook issues

​Data discrepancies

​Getting help

​Common error messages

​Next steps

API Reference

Custom Dashboards

Webhooks

Migration Guide

Build docs developers (and LLMs) love

Events not appearing

Performance issues

Tracking accuracy

Integration issues

Webhook issues

Data discrepancies

Getting help

Common error messages

Next steps