Mixpanel Troubleshooting & Debugging

Overview

This guide helps you diagnose and resolve common Mixpanel tracking issues. Mixpanel provides product analytics with event-based tracking, making proper implementation critical for accurate insights.

Debug Mode

Enable Debug Mode

Enable debug mode to see detailed tracking information:

// Enable debug mode for Mixpanel
mixpanel.set_config({ debug: true });

// Or enable on initialization
mixpanel.init('YOUR_PROJECT_TOKEN', { debug: true });

Check Mixpanel Loading

Verify Mixpanel is loaded correctly:

// Check if Mixpanel is loaded
if (typeof mixpanel !== 'undefined' && mixpanel.__loaded) {
  console.log('Mixpanel loaded successfully');
  console.log('Project token:', mixpanel.get_config('token'));
} else {
  console.error('Mixpanel not loaded');
}

// Check distinct ID
if (typeof mixpanel !== 'undefined') {
  mixpanel.get_distinct_id(function(distinct_id) {
    console.log('Distinct ID:', distinct_id);
  });
}

Common Issues

No Data in Reports

Symptoms: Tracking code installed but no events appear in Mixpanel.

Solutions:

Verify project token:

// Check your project token is correct
console.log('Token:', mixpanel.get_config('token'));

// Should match token in Project Settings

Check script installation:

<!-- Mixpanel tracking code should be in <head> -->
<script type="text/javascript">
(function(f,b){if(!b.__SV){var e,g,i,h;window.mixpanel=b;b._i=[];b.init=function(e,f,c){function g(a,d){var b=d.split(".");2==b.length&&(a=a[b[0]],d=b[1]);a[d]=function(){a.push([d].concat(Array.prototype.slice.call(arguments,0)))}}var a=b;"undefined"!==typeof c?a=b[c]=[]:c="mixpanel";a.people=a.people||[];a.toString=function(a){var d="mixpanel";"mixpanel"!==c&&(d+="."+c);a||(d+=" (stub)");return d};a.people.toString=function(){return a.toString(1)+".people (stub)"};i="disable time_event track track_pageview track_links track_forms track_with_groups add_group set_group remove_group register register_once alias unregister identify name_tag set_config reset opt_in_tracking opt_out_tracking has_opted_in_tracking has_opted_out_tracking clear_opt_in_out_tracking start_batch_senders people.set people.set_once people.unset people.increment people.append people.union people.track_charge people.clear_charges people.delete_user people.remove".split(" ");
for(h=0;h<i.length;h++)g(a,i[h]);var j="set set_once union unset remove delete".split(" ");a.get_group=function(){function b(c){d[c]=function(){call2_args=arguments;call2=[c].concat(Array.prototype.slice.call(call2_args,0));a.push([e,call2])}}for(var d={},e=["get_group"].concat(Array.prototype.slice.call(arguments,0)),c=0;c<j.length;c++)b(j[c]);return d};b._i.push([e,f,c])};b.__SV=1.2;e=f.createElement("script");e.type="text/javascript";e.async=!0;e.src="undefined"!==typeof MIXPANEL_CUSTOM_LIB_URL?MIXPANEL_CUSTOM_LIB_URL:"file:"===f.location.protocol&&"//cdn.mxpnl.com/libs/mixpanel-2-latest.min.js".match(/^\/\//)?"https://cdn.mxpnl.com/libs/mixpanel-2-latest.min.js":"//cdn.mxpnl.com/libs/mixpanel-2-latest.min.js";g=f.getElementsByTagName("script")[0];g.parentNode.insertBefore(e,g)}})(document,window.mixpanel||[]);

mixpanel.init('YOUR_PROJECT_TOKEN');
</script>

Verify network requests:
- Open DevTools → Network tab
- Filter by "mixpanel" or "track"
- Look for requests to api.mixpanel.com
- Status should be 200 (Success)
Check for ad blockers:
- Disable browser extensions
- Test in incognito/private mode
- Ad blockers often block Mixpanel
Enable debug mode and test:

mixpanel.set_config({ debug: true });
mixpanel.track('Test Event', { test: true });
// Check console for request details

Events Not Tracking

Symptoms: Custom events aren't appearing in Mixpanel.

Solutions:

Verify event syntax:

// Correct event tracking
mixpanel.track('Button Clicked', {
  'button_name': 'Sign Up',
  'page': 'Homepage',
  'user_type': 'Free'
});

// Check in console with debug mode
mixpanel.set_config({ debug: true });
mixpanel.track('Test Event');

Check event name rules:
- Event names are case-sensitive
- Use consistent naming conventions
- Avoid special characters

// Good event names
mixpanel.track('Purchase Completed');
mixpanel.track('Video Played');

// Inconsistent (creates separate events)
mixpanel.track('purchase completed');  // Different case
mixpanel.track('Purchase_Completed');  // Different separator

Verify properties:

// Valid property types
mixpanel.track('Event Name', {
  'string': 'value',
  'number': 123,
  'boolean': true,
  'date': new Date().toISOString()
});

// Don't use complex types
mixpanel.track('Bad Event', {
  'function': function() {},  // Won't work
  'object': { nested: 'data' }  // Won't work (unless stringified)
});

Check timing:
- Events appear in Live View immediately
- Reports may take a few minutes to update
- Historical data processes hourly

User Identification Not Working

Symptoms: Users aren't being identified or aliased correctly.

Solutions:

Use identify() correctly:

// Identify user
mixpanel.identify('user_12345');

// Verify distinct ID
console.log('Distinct ID:', mixpanel.get_distinct_id());

// Set user properties
mixpanel.people.set({
  '$email': 'user@example.com',
  '$name': 'John Doe',
  'plan': 'premium',
  'signup_date': new Date().toISOString()
});

Alias users correctly:

// When user signs up, create alias
// Old anonymous ID → New user ID
var anonymousId = mixpanel.get_distinct_id();
mixpanel.alias('user_12345', anonymousId);
mixpanel.identify('user_12345');

// IMPORTANT: Only call alias once per user

Common aliasing mistakes:

// ❌ Don't call alias multiple times
mixpanel.alias('user_12345');
mixpanel.alias('user_12345');  // Creates duplicate

// ✓ Call alias only on signup
function onSignup(userId) {
  mixpanel.alias(userId);
  mixpanel.people.set({ '$email': user.email });
}

// ✓ Call identify on login
function onLogin(userId) {
  mixpanel.identify(userId);
  mixpanel.people.set({ '$last_login': new Date() });
}

Reset identity:

// Reset identity (e.g., on logout)
mixpanel.reset();

// Generates new anonymous distinct_id
console.log('New distinct ID:', mixpanel.get_distinct_id());

People Properties Not Updating

Symptoms: User profile properties not showing in Mixpanel.

Solutions:

Set people properties:

// Set properties (overwrites existing)
mixpanel.people.set({
  '$email': 'user@example.com',
  '$name': 'John Doe',
  'plan': 'premium'
});

// Set once (only if not already set)
mixpanel.people.set_once({
  'signup_date': new Date().toISOString()
});

// Increment numeric property
mixpanel.people.increment('page_views', 1);

// Append to list property
mixpanel.people.append('purchases', 'Product A');

Ensure identify() is called:

// MUST call identify before setting people properties
mixpanel.identify('user_12345');
mixpanel.people.set({ '$email': 'user@example.com' });

// Won't work without identify:
// mixpanel.people.set({ '$email': 'user@example.com' });

Check for errors:

mixpanel.set_config({ debug: true });
mixpanel.identify('user_12345');
mixpanel.people.set({ '$email': 'user@example.com' });
// Check console for errors

Group Analytics Not Working

Symptoms: Group-level analytics not tracking.

Solutions:

Set up group key:

// First, create group key in Mixpanel Project Settings

// Set group for user
mixpanel.set_group('company', 'Company123');

// Track event with group
mixpanel.track('Feature Used');  // Automatically includes group

// Set group properties
mixpanel.get_group('company', 'Company123').set({
  'name': 'Acme Corp',
  'plan': 'Enterprise',
  'employees': 500
});

Track with multiple groups:

// User can belong to multiple groups
mixpanel.add_group('company', 'Company123');
mixpanel.add_group('team', 'Team456');

// Remove from group
mixpanel.remove_group('team', 'Team456');

Debugging Techniques

Comprehensive Health Check

// Complete Mixpanel diagnostic
function mixpanelHealthCheck() {
  console.group('Mixpanel Health Check');

  // 1. Check if loaded
  if (typeof mixpanel === 'undefined') {
    console.error('❌ Mixpanel not loaded');
    console.groupEnd();
    return;
  }
  console.log('✓ Mixpanel loaded');

  // 2. Check configuration
  console.log('Token:', mixpanel.get_config('token'));
  console.log('API host:', mixpanel.get_config('api_host'));
  console.log('Debug:', mixpanel.get_config('debug'));

  // 3. Check identity
  console.log('Distinct ID:', mixpanel.get_distinct_id());

  // 4. Test tracking
  mixpanel.track('Health Check Test', {
    timestamp: new Date().toISOString()
  });
  console.log('✓ Test event sent');

  console.groupEnd();
}

mixpanelHealthCheck();

Monitor Tracking Calls

// Log all Mixpanel tracking
const originalTrack = mixpanel.track;
mixpanel.track = function() {
  console.log('mixpanel.track called:', arguments);
  return originalTrack.apply(this, arguments);
};

const originalIdentify = mixpanel.identify;
mixpanel.identify = function() {
  console.log('mixpanel.identify called:', arguments);
  return originalIdentify.apply(this, arguments);
};

Verify Super Properties

// Check registered super properties
function checkSuperProperties() {
  // Register super properties (sent with every event)
  mixpanel.register({
    'app_version': '2.1.0',
    'platform': 'web'
  });

  // Get all super properties
  console.log('Super properties:', mixpanel.persistence.properties());

  // Register once (won't overwrite)
  mixpanel.register_once({
    'initial_referrer': document.referrer
  });

  // Unregister property
  mixpanel.unregister('app_version');
}

checkSuperProperties();

Browser-Specific Issues

Safari ITP (Intelligent Tracking Prevention)

// Mixpanel uses first-party cookies for better ITP compatibility
// Configure persistence explicitly
mixpanel.init('YOUR_PROJECT_TOKEN', {
  persistence: 'localStorage',  // or 'cookie'
  cross_subdomain_cookie: false
});

Content Security Policy (CSP)

<!-- Add Mixpanel domains to CSP -->
<meta http-equiv="Content-Security-Policy"
      content="script-src 'self' https://cdn.mxpnl.com 'unsafe-inline';
               connect-src 'self' https://api.mixpanel.com;">

Ad Blockers

// Detect if Mixpanel is blocked
setTimeout(function() {
  if (typeof mixpanel === 'undefined' || !mixpanel.__loaded) {
    console.warn('Mixpanel likely blocked by ad blocker');

    // Use proxy or server-side tracking
    // Or send to alternative analytics
  }
}, 2000);

Data Quality Issues

Duplicate Events

// Prevent duplicate event tracking
let eventTracked = {};

function trackOnce(eventName, properties) {
  const key = eventName + JSON.stringify(properties);
  if (!eventTracked[key]) {
    mixpanel.track(eventName, properties);
    eventTracked[key] = true;

    // Clear after 5 seconds
    setTimeout(() => {
      delete eventTracked[key];
    }, 5000);
  }
}

// Use for critical events
trackOnce('Purchase', { order_id: '12345' });

Invalid Property Names

// Validate property names
function trackWithValidation(eventName, properties) {
  const validProperties = {};

  for (const key in properties) {
    // Mixpanel reserved prefixes: $, mp_
    if (key.startsWith('$') || key.startsWith('mp_')) {
      console.warn(`Reserved property name: ${key}`);
      continue;
    }

    validProperties[key] = properties[key];
  }

  mixpanel.track(eventName, validProperties);
}

trackWithValidation('Event', {
  'custom_prop': 'ok',        // ✓
  '$reserved': 'not ok'       // ✗ Will be filtered
});

Bot Traffic

// Filter bot traffic
if (!/bot|crawler|spider/i.test(navigator.userAgent)) {
  mixpanel.track('Page View');
} else {
  console.log('Bot detected - not tracking');
}

Performance Issues

Script Loading Impact

<!-- Load Mixpanel asynchronously (default behavior) -->
<script async src="https://cdn.mxpnl.com/libs/mixpanel-2-latest.min.js"></script>

<!-- Or use defer -->
<script defer src="https://cdn.mxpnl.com/libs/mixpanel-2-latest.min.js"></script>

Batch Events

// Batch events for better performance
mixpanel.set_config({ batch_requests: true });

// Events will be sent in batches
mixpanel.track('Event 1');
mixpanel.track('Event 2');
mixpanel.track('Event 3');
// All sent together in one request

Getting Help

Check Mixpanel Status

Visit status.mixpanel.com to check for service interruptions.

Enable Maximum Debugging

// Enable all debug features
mixpanel.set_config({
  debug: true,
  verbose: true
});

// Log complete state
console.log('Mixpanel Config:', {
  token: mixpanel.get_config('token'),
  distinct_id: mixpanel.get_distinct_id(),
  api_host: mixpanel.get_config('api_host'),
  persistence: mixpanel.get_config('persistence'),
  super_properties: mixpanel.persistence.properties()
});

// Test all major functions
mixpanel.track('Debug Test');
mixpanel.identify('test_user');
mixpanel.people.set({ test: true });
mixpanel.register({ debug: true });

Contact Support

If issues persist:

Collect debug information:
- Browser and version
- Mixpanel project token
- Console errors/warnings
- Network request details
- Steps to reproduce
Contact Mixpanel Support:
- In-app chat (available in dashboard)
- Email: support@mixpanel.com
- Include all debug information
Mixpanel Documentation:
- Visit docs.mixpanel.com
- API reference
- Integration guides
- Video tutorials

Best Practices

Regular Testing

// Create test suite
function runMixpanelTests() {
  console.group('Mixpanel Tests');

  // Enable debug
  mixpanel.set_config({ debug: true });

  // 1. Test event tracking
  mixpanel.track('Test Event', { test: true });
  console.log('✓ Event tracked');

  // 2. Test user identification
  mixpanel.identify('test_user_' + Date.now());
  console.log('✓ User identified');

  // 3. Test people properties
  mixpanel.people.set({ test_prop: true });
  console.log('✓ People property set');

  // 4. Test super properties
  mixpanel.register({ test_super: true });
  console.log('✓ Super property registered');

  console.groupEnd();
}

runMixpanelTests();

Monitor in Production

// Log Mixpanel errors
window.addEventListener('error', function(e) {
  if (e.message && e.message.includes('mixpanel')) {
    console.error('Mixpanel error:', e);
    // Send to error tracking service
  }
});

// Monitor Mixpanel availability
setInterval(function() {
  if (typeof mixpanel === 'undefined') {
    console.error('Mixpanel not available');
    // Alert monitoring service
  }
}, 60000); // Check every minute

Testing Checklist

Mixpanel script loaded successfully
Project token is correct
Events tracking correctly
User identification working
People properties being set
Super properties registered
Group analytics working (if used)
No console errors
Network requests successful
Data appearing in Live View