Understanding and Resolving Cardinality Limit Exceeded Error
What does the cardinality limit exceeded error mean? Why does it appear? How do I resolve it?
What does the cardinality limit exceeded error mean? Why does it appear? How do I resolve it?
Hi Jorge C., 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
A “cardinality limit exceeded” error means your query is returning more unique segments (breakdown values) than the Mixpanel UI is allowed to display, so the results are truncated to only the top N segments. [Reports overview]
Why it appears
It shows up when: - You have many unique values for a breakdown property (e.g., user IDs, UUIDs, very granular IDs). - Your query uses wide time ranges, many breakdowns, or both, which multiplies the number of segments. When the result set exceeds the segment “visible limit” for that report type (e.g., 3000 for Insights), Mixpanel truncates and shows the cardinality error or “-” instead of values for segments that could not be returned. [Reports overview]
How to resolve it
Reduce the number of segments returned by your query: 1. Narrow the time range (e.g., last 7 or 30 days instead of months/years). [Reports overview] 2. Add filters on: - Specific events - Specific property values (e.g., only top countries, limited product set) [Reports overview] 3. Reduce or simplify breakdowns: - Use fewer breakdown properties - Break down by lower-cardinality properties (e.g., Country instead of User ID). [Reports overview] 4. Use CSV export if you need more segments than the UI can show: - Most reports: up to 10,000 segments - Insights non-line charts: up to 50,000 segments [Reports overview]If you still hit limits after narrowing, it likely indicates extremely high-cardinality properties or an implementation pattern (e.g., IDs in event/property names) that may need revisiting.
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! 📚
Yes. In your case the error is very likely caused by the very high number of unique values returned by that custom ID field when you use Distinct count in Insights.Mixpanel’s UI can only display up to a certain number of segments (unique breakdown values). When a breakdown returns more unique segments than this “visible limit” (e.g. thousands–millions of IDs), Mixpanel truncates the result to the top N segments and shows a cardinality limit error or “-” instead of full results. [Segment limits]To work around this when you expect millions of IDs: - Don’t break down by that custom ID directly, or - Filter to a much smaller subset of IDs or time range, or - Use a lower-cardinality property for breakdown, and keep your distinct-count-on-ID only as the metric, not as the breakdown dimension.These steps reduce the number of returned segments so the query stays under the UI cardinality limits. [Segment limits]
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! 📚
You’re right to expect a single number/line if you’re not breaking down by that custom ID. The cardinality error in Mixpanel, however, is explicitly documented as being tied to breakdown segment limits, not to the size of the distinct count itself. [Segment limits]From the docs: - The error appears when a query “returned more unique segments than the UI can display” and is resolved by “narrow[ing] the time range, apply[ing] filters, or reduc[ing] the number of breakdowns.” [Segment limits] - Limits are defined per visualization type (e.g., Insights line: visible limit 3000 segments). [Segment limits]The knowledge sources do not mention cardinality limits being applied to a single metric with no breakdowns, even if that metric is a distinct count over millions of IDs. They only describe limits on segments from breakdowns.So based on the docs: - Just having millions of distinct IDs in the metric (with no breakdown) should not, according to the documentation, trigger the “cardinality limit exceeded” message. - The documented causes are: - Too many breakdown segments - Multi-breakdown flattening causing many segment combinations - UI segment-visible limits being hit [Segment limits]Because the docs don’t describe your specific pattern (cardinality error on a single, unsegmented metric), I can’t definitively say why you’re seeing it from the available sources. The most I can say with confidence is: - Officially documented reason: too many segments from breakdowns, not just a large distinct count. - Your situation is not explicitly covered in the docs, so the knowledge sources are insufficient to fully explain this behavior.Given that, the safest next steps (based on the docs) are: 1. Double‑check that there is no implicit breakdown (e.g., saved metric, cohort, or group breakdown) affecting the query. 2. Try a very short date range to see if the message persists (recommended by docs to reduce segments). [Segment limits] 3. If it still happens with absolutely no breakdowns, this is behavior not described in the documentation, and you’d need Mixpanel Support to inspect the specific query/project.
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.