/grouping-noisy-errors

name: grouping-noisy-errors
description: >
  Consolidate PostHog error tracking issues that are the same actual
  error reported under different fingerprints. Use when the user asks
  "why do I have so many TypeError issues that look the same?", "merge
  these duplicates", "stop splitting this error into new issues", or
  wants to clean up fingerprint sprawl. Decides between a one-shot merge
  of existing issues and a durable grouping rule that keeps future
  events from creating new fingerprints. Does NOT group conceptually
  similar bugs across different runtimes, SDKs, or call sites.

Grouping noisy errors

The same error can be reported as dozens of separate issues when stack frames or messages contain volatile data — random IDs, dynamic file paths, build hashes, anonymous function names. The fix is two-step: merge the existing issues into one target, then create a grouping rule so future events from the same call site share a single canonical fingerprint instead of spawning new ones.

Important up front: "same error" here is narrow. Two issues that share a name or a sentence of message text but came from different code paths, different SDKs, or different runtimes are **different errors** and should stay separate, even if the user thinks of them as "the same kind of bug". Grouping a frontend `TypeError` together with a backend `TypeError` because both messages contain "undefined" destroys the signal that lets the team find each one. The criteria in step 1 exist to keep that from happening.

Available tools

| Tool | Purpose | | ---------------------------------------------- | ------------------------------------------------------ | | `posthog:query-error-tracking-issues-list` | Find candidate duplicate issues | | `posthog:query-error-tracking-issue` | Pull compact details for an individual issue | | `posthog:query-error-tracking-issue-events` | Sampled `$exception` events with stack and message | | `posthog:error-tracking-issues-merge-create` | Merge existing issues into a target | | `posthog:error-tracking-issues-split-create` | Surgically split fingerprints back out if a merge errs | | `posthog:error-tracking-grouping-rules-create` | Auto-group future events into one issue | | `posthog:error-tracking-grouping-rules-list` | Check existing grouping rules before adding new ones | | `posthog:error-tracking-issues-partial-update` | Rename or re-describe the target after a merge |

Merge vs grouping rule

The two tools solve different halves of the problem:

• **Merge** is one-shot. It collapses existing issues into a target and re-attaches

their events. Future events still group by their original fingerprints — if the same noisy pattern keeps producing new fingerprints, merging is a treadmill.

• **Grouping rule** is durable. It rewrites the fingerprint of any matching

event to `custom-rule:<rule_id>` at ingestion time, so all future matches share one canonical fingerprint rather than spawning new ones. The first match either creates a new issue keyed off that fingerprint, or routes to whatever issue is already bound to it.

Use both together when the issue is recurring: merge historical duplicates into a target issue, then create the rule. The rule API does **not** accept a target issue ID — once the rule starts firing, the resulting `custom-rule:...` issue can be merged into the same target so the consolidation sticks. Use merge alone for historical sprawl that you don't expect to recur. Use a grouping rule alone for a brand-new pattern you're getting ahead of, when you don't need to consolidate with an existing issue.

Workflow

Step 1 — Confirm the duplicates

Search by exception type or message to find candidates:

posthog:query-error-tracking-issues-list
{
  "searchQuery": "TypeError: Cannot read property",
  "status": "active",
  "limit": 50,
  "orderBy": "occurrences",
  "dateRange": { "date_from": "-30d" }
}

For each candidate, pull one sampled exception event to compare stack, type, and message:

posthog:query-error-tracking-issue-events
{
  "issueId": "<candidate_issue_id>",
  "limit": 1,
  "include": ["exception", "stacktrace", "environment"]
}

Run this once per candidate. The tool defaults to `onlyAppFrames: true`, which makes the top in-app frame stand out at a glance. If two candidates share the same top frame and same exception type, they're likely the same error — but verify against the full checklist below before merging.

Are they the same error?

Treat two issues as duplicates only when **every one** of these matches:

• `$lib` is the same SDK. The browser/JS SDK captures `$lib` as `web` (not

`posthog-js`); server SDKs use `posthog-python`, `posthog-node`, etc. Confirm the exact value with `read-data-schema` (`event_property_values` for `$lib` on `$exception`) rather than assuming — a wrong value silently matches nothing. Errors from different SDKs almost always come from different code paths even when the exception type matches.

• The exception type is identical (`$exception_types`).
• The top in-app stack frame points at the same file and same function. Line

numbers and minor offsets within that function are fine; a different file or a different function on top means a different bug.

• The message follows the same template, with differences confined to volatile

data — IDs, hashes, timestamps, dynamic paths. If the difference is a different verb, object, or operation, it's a different bug.

• `$exception_handled` agrees (both handled or both unhandled). A caught

variant and an uncaught variant are different code paths and benefit from staying separate.

If any single one of those differs, they are not duplicates — investigate separately (`investigating-error-issue`).

What NOT to group t