Hi, I need some help, could you point me to the right direction? we are seeing a lot of projects and Project Id's not set in our mixpanel metrics and events. when looking at the events they have the error message: too many distinctIDs mapped together, Max limit: 500, how do I debug this?
Hi Elias B., Please stand by as I search the Mixpanel knowledge base for an AI-powered answer. I normally take about 15 seconds or so. In case AI cannot answer your question, feel free to reach out to Mixpanel support at mixpanel.com/get-support. If you have follow-up questions for this thread, please tag me again with your question: @kapa.ai <follow-up question> đź‘‹
Feel free to ask a follow-up question once I've answered by mentioning me with @kapa.ai
You're encountering the error: "too many distinctIDs mapped together, Max limit: 500" This is related to Mixpanel's Original ID Merge system, which limits each user's identity cluster to a maximum of 500 distinct IDs. When this limit is reached, new distinct IDs cannot be merged into the same cluster, resulting in orphaned (duplicate) users and incomplete user journeys in your analytics.
Why does this happen?
- This typically occurs when the process of generating new anonymous IDs (often via .reset() calls on logout) and then merging them to the same user repeats many times—eventually hitting the 500 ID cluster limit.
- This is common in apps where multiple users share the same device, and .reset() is called frequently to clear the previous user's state before a new user logs in. Each .reset() generates a new anonymous ID, which, when merged, increases the cluster size. If this happens 500 times for a single user, you hit the limit and see this error.
See more details here.
How to debug and resolve:
1. Identify the affected users and events:
- Use Mixpanel's reporting tools to find which distinct IDs and events are involved. You can use a pre-built board to help identify the main distinct IDs and event names causing the issue. This will help you see which users are hitting the limit and what actions are leading to it
Recovering from a hot shard.2. Review your implementation:
- Check your use of .reset(). If you are calling .reset() on every logout, and your app is not truly a shared device scenario, consider removing or limiting its use. Only call .reset() when you explicitly need to clear the user state for a new, different user (e.g., on a "Sign Up" screen for a new user, not just on every logout)
Best practices for .reset().
- Ensure that you are not generating new anonymous IDs unnecessarily, as this will quickly increase the number of IDs in a cluster.3. Consider your ID management strategy:
- If you do not need to support multiple users per device, you likely do not need frequent .reset() calls and can avoid hitting the 500 ID limit.
- If you are starting a new project, consider using the Simplified ID Merge system, which does not have this 500 ID cluster limit. However, you cannot switch ID management systems for an existing project with data
Migrating to Simplified ID Merge.4. Fix historical data (optional):
- If you need to clean up historical data, you can export, transform, and re-import the data, but this is an advanced process and may not always be necessary
Recovering from a hot shard.
Summary of next steps:
- Audit your .reset() and .identify() usage.
- Limit .reset() to true user-switching scenarios.
- Use Mixpanel's tools to identify affected users and events.
- Consider Simplified ID Merge for new projects if you want to avoid this limitation in the future.If you need further help, you can reach out to Mixpanel support with details of your investigation.Let me know if you need more specific guidance on any of these steps!
kapa.ai is still learning and improving, please let me know how I did by reacting below.
ℹ️ Tip: Mention @kapa.ai in the thread for follow-ups or DM the app for 1-to-1 help.
Let me check the knowledge base for you again. One moment! đź“š
It is not possible to switch an existing Mixpanel project (that already contains data) to use Simplified ID Merge. This is because Simplified ID Merge uses a fundamentally different backend architecture, and Mixpanel does not support converting projects with existing data from Legacy or Original ID Merge to Simplified ID Merge. To use Simplified ID Merge, you must create a new, empty Mixpanel project and enable Simplified ID Merge before sending any data to it. Once data has been ingested into a project, the identity management version cannot be changed. Both Original and Simplified ID Merge will continue to be supported, but migration requires setting up a new project and migrating your data and configuration manually if needed Deciding to Migrate Identity Merge APIs.In summary: Switching an existing project to Simplified ID Merge is not feasible. You would need to create a new project and migrate your implementation and data if you want to use Simplified ID Merge.
kapa.ai is still learning and improving, please let me know how I did by reacting below.
ℹ️ Tip: Mention @kapa.ai in the thread for follow-ups or DM the app for 1-to-1 help.
