> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/mixpanel/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Guide

> Solutions to common issues when using Mixpanel

# Troubleshooting Guide

Find solutions to common issues when implementing and using Mixpanel.

## Data Not Appearing

### No data showing in my project

**Problem:** Events are not appearing in your Mixpanel project after implementation.

**Common Causes:**

1. **Incorrect Project Token**
   * Verify you're using the correct project token from [Project Settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens)
   * Check that the token matches your intended project (Dev vs Production)

2. **Data Residency Mismatch**
   * If your project uses EU or India residency, ensure your SDK is pointing to the correct API endpoint
   * EU endpoint: `api-eu.mixpanel.com`
   * India endpoint: `api-in.mixpanel.com`
   * Learn more: [EU Residency](/docs/privacy/eu-residency) | [India Residency](/docs/privacy/in-residency)

3. **Implementation Errors**
   * Enable [debug mode](/docs/tracking-best-practices/debugging#enable-debug-mode) in your SDK to see console logs
   * Check browser console or server logs for error messages
   * Verify SDK initialization happens before tracking calls

**Solutions:**

* Use the [Mixpanel Data Inspector](/docs/tracking-methods/data-inspector) browser extension to verify events are being sent
* Check the [Events page](/docs/data-governance/events) in your project to see recent activity
* Review our [debugging guide](/docs/tracking-best-practices/debugging) for detailed troubleshooting steps

### Events not appearing in real-time

**Problem:** Events take time to appear in reports or the Events page.

**Explanation:** Mixpanel ingests events in near real-time, but there can be a delay of 1-2 minutes for events to be fully processed and queryable. For historical imports (events with timestamps older than 5 days), there may be additional processing time.

**Solutions:**

* Wait 2-5 minutes after sending events before checking reports
* Use the Events page to verify events are being received
* For historical imports, check the import job status in Warehouse Connectors settings

## Identity Management Issues

### Multiple profiles for the same user

**Problem:** A single user appears as multiple distinct profiles in Mixpanel.

**Common Causes:**

* Different `distinct_id` values assigned to the same user across different platforms or sessions
* Not calling `identify()` consistently at login/registration
* Sending data from multiple sources (web, mobile, CDP) with different identifiers

**Solutions:**

1. Ensure you call `identify()` with the same user ID across all platforms
2. Use a consistent identifier (like user ID, email) when calling `identify()`
3. Review [identity management best practices](/docs/tracking-methods/id-management/identifying-users-simplified)
4. Check all data sources are using the same identification logic

### Data from different users merged into one profile

**Problem:** Events from different users appear under a single profile.

**Common Causes:**

* Not calling `reset()` when users log out on shared devices
* Reusing the same `distinct_id` for multiple users on server-side

**Solutions:**

1. Always call `reset()` on logout to clear the current user's identity
2. Generate unique identifiers for each user on server-side implementations
3. Review the [client-side identity management guide](/docs/tracking-methods/id-management/identifying-users-simplified)

## Tracking Issues

### Ad-blockers preventing tracking

**Problem:** Events are blocked by ad-blockers or privacy extensions.

**Impact:** Up to 30% of client-side events may be blocked depending on your audience.

**Solutions:**

1. **Server-side tracking** - Track critical events (purchases, signups) from your server
2. **Proxy setup** - Route Mixpanel requests through your own domain
3. **Hybrid approach** - Use server-side for business-critical events and client-side for user interactions

Learn more: [Choosing the Right Tracking Method](/docs/tracking-methods/choosing-the-right-method)

### CORS errors in browser console

**Problem:** CORS (Cross-Origin Resource Sharing) errors appear when Mixpanel requests are made.

**Common Causes:**

* Browser security policy blocking cross-origin requests
* Missing or incorrect CORS headers

**Solutions:**

1. Verify Mixpanel SDK is properly initialized with your project token
2. Check that you're using the correct API endpoint for your data residency
3. If using a proxy, ensure CORS headers are properly configured
4. Review [MDN CORS documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS/Errors) for detailed debugging

### Events tracked but properties missing

**Problem:** Events appear in Mixpanel but expected properties are not present.

**Common Causes:**

* Property values are `null`, `undefined`, or empty strings
* Property names have typos or case sensitivity issues (Mixpanel is case-sensitive)
* Properties not included in the tracking call

**Solutions:**

1. Use debug mode to log the exact payload being sent
2. Check the Events page to inspect individual event properties
3. Verify property names match exactly (case-sensitive)
4. Ensure property values are valid (not null, undefined, or empty)

## Geolocation Issues

### All users showing the same location

**Problem:** User profiles display the same location (e.g., Virginia, Oregon).

**Common Cause:** Server-side implementation or CDP sending events with the server's IP address instead of the user's IP.

**Solutions:**

1. **Pass user's IP** - Include the actual client IP in the `$ip` property
2. **Set location manually** - Use `$city`, `$region`, and `$country_code` properties
3. **Disable geolocation** - Set `$ip` to `0` to prevent automatic geolocation updates

Learn more: [Geolocation Best Practices](/docs/tracking-best-practices/geolocation)

## Report and Query Issues

### Report results don't match expectations

**Problem:** A report shows unexpected results or data doesn't align with other sources.

**Troubleshooting Steps:**

1. **Verify filters** - Check if global or inline filters are excluding data
2. **Check date range** - Ensure the date range matches your expectations
3. **Review report logic** - Understand how the specific report type calculates results ([Insights](/docs/reports/insights), [Funnels](/docs/reports/funnels/funnels-overview), etc.)
4. **Inspect individual events** - Find a specific user/event that should be included and verify why it is or isn't
5. **Time zone settings** - Verify your project timezone matches your expectations

**Getting Help:**
If you still need assistance, [contact Support](https://mixpanel.com/get-support) with:

* A link to the report
* Description of what looks incorrect
* Example of a specific user or event that should/shouldn't be included

### Can't find events in report dropdown

**Problem:** Events don't appear in the event selection dropdown when building reports.

**Common Causes:**

* Events are older than 30 days and haven't been queried recently
* Events are hidden in Lexicon
* No events with that name in the selected date range

**Solutions:**

1. Type the exact event name (including case sensitivity) in the search box
2. Check [Lexicon](/docs/data-governance/lexicon) to see if the event is hidden
3. Verify events exist in your project using the Events page
4. For historical imports, query the data first to make events appear in dropdowns

## SDK and Integration Issues

### SDK not initializing

**Problem:** Mixpanel SDK fails to initialize or throws errors.

**Solutions:**

1. Verify the SDK is loaded before calling `init()`
2. Check for JavaScript errors in the console that might be blocking execution
3. Ensure the project token is valid and properly formatted
4. Review the SDK installation guide for your platform: [JavaScript](/docs/tracking-methods/sdks/javascript) | [iOS](/docs/tracking-methods/sdks/swift) | [Android](/docs/tracking-methods/sdks/android)

### Integration not sending data

**Problem:** Data from CDPs (like Segment) or warehouse connectors not appearing in Mixpanel.

**Solutions:**

1. **CDP Integration:**
   * Verify Mixpanel is enabled as a destination
   * Check destination settings and mappings
   * Review the integration's event delivery logs
   * Ensure project token is correct

2. **Warehouse Connectors:**
   * Check sync status and logs in [Warehouse Data settings](https://mixpanel.com/report/settings#warehouse-data)
   * Verify warehouse credentials and permissions
   * Review column mappings (Event Name, Time, Distinct ID)
   * Ensure data formats match Mixpanel requirements

Learn more: [Warehouse Connectors](/docs/tracking-methods/warehouse-connectors) | [CDP Integrations](/docs/tracking-methods/integrations)

## Performance Issues

### Slow query or report loading

**Problem:** Reports take a long time to load or queries time out.

**Common Causes:**

* Very large date ranges
* Complex breakdowns with high cardinality properties
* Querying across millions of events

**Solutions:**

1. Reduce the date range to a shorter period
2. Limit breakdowns to properties with reasonable cardinality
3. Use [cohorts](/docs/users/cohorts) to pre-filter users before querying
4. Consider using [custom events](/docs/features/custom-events) to pre-aggregate data

## Data Quality Issues

### Duplicate events

**Problem:** The same event appears multiple times for a single user action.

**Common Causes:**

* Not using `$insert_id` to deduplicate events
* SDK or tracking code called multiple times
* Retry logic sending events multiple times

**Solutions:**

1. Always include a unique `$insert_id` property for each event
2. Review your implementation to ensure tracking isn't triggered multiple times
3. Use [debug mode](/docs/tracking-best-practices/debugging#enable-debug-mode) to see when events are sent

Learn more: [Preventing Duplicate Events](/docs/tracking-best-practices/server-side-best-practices#preventing-duplicates)

### Bot traffic in data

**Problem:** Events from bots or crawlers polluting your data.

**Solutions:**

1. Mixpanel's JavaScript SDK automatically blocks known crawlers
2. Implement custom filtering by setting `$ignore: true` for bot traffic
3. Use server-side validation to filter bot requests
4. Review [bot traffic management guide](/docs/tracking-best-practices/bot-traffic)

## Getting Additional Help

If you continue to experience issues after trying these solutions:

1. **Check the documentation** - Search our [docs](/) for detailed guides
2. **Slack Community** - Join our [community](https://community.mixpanel.com/) to ask questions
3. **Contact Support** - [Submit a support request](https://mixpanel.com/get-support) with:
   * Detailed description of the issue
   * Steps to reproduce
   * Screenshots or screen recordings
   * Links to relevant reports or profiles
   * Browser console logs or SDK debug output

***

**Related Resources:**

* [Debugging Guide](/docs/tracking-best-practices/debugging)
* [FAQs](/resources/faqs)
* [Best Practices](/docs/tracking-best-practices)