Error Grouping Explained: Fingerprints & Merging

Turn duplicate reports into one fixable issue

Error grouping turns repeated crashes, exceptions, and log errors into clean issues. Telebugs gives you sensible defaults, custom fingerprints, grouping details, and manual merge controls.

Error grouping in Telebugs turns duplicate reports into clear issues

Error grouping in Telebugs turns duplicate reports into clear issues you can actually fix.

Quick answer: what is error grouping?

Error grouping is the process of turning many similar error events into one issue. Instead of showing 500 separate reports for the same production bug, an error tracker looks at signals such as a custom fingerprint, stack trace, exception type, exception message, and source location, then keeps related events together.

Good grouping is what makes error tracking usable. It reduces duplicate noise, keeps alerting sane, preserves the individual reports for debugging, and gives your team one place to resolve, assign, snooze, or discuss the underlying bug.

Why error grouping matters

When an error happens in production, it rarely happens just once. A single bug can generate hundreds or thousands of nearly identical reports. These have the same stack trace, the same message, the same context, just with slightly different user data or timestamps.

Without smart grouping, your error list becomes noise. You waste time triaging duplicates instead of fixing root causes. In high-volume apps this quickly becomes unmanageable, especially if you're paying per event or fighting alert fatigue.

Telebugs solves this at the core: it automatically groups similar reports into issues so you see one clear problem instead of a flood of reports. The grouping relies on practical signals developers already understand: fingerprints, in-app stack frames, exception type, message, and source context.

How Telebugs groups errors

Telebugs accepts Sentry SDK compatible error events, which means your applications can keep sending the same useful grouping signals they already send to Sentry: fingerprints, stack frames, exception metadata, tags, release names, and environment.

  • Custom fingerprint: If the SDK sends a fingerprint, Telebugs can use it to group events according to your own business logic.
  • Stack trace: Telebugs prefers the oldest causal exception with a useful stack, then selects application frames before unknown or framework-only frames.
  • Exception type and value: When stack traces are missing or less useful, the error class and message help keep related exceptions together.
  • Message fallback: Captured messages and log-style events still need a group, even when they do not include a rich exception payload.
  • Stable boundaries: Default grouping stays platform-specific, while a complete custom fingerprint can deliberately group events across languages or platforms.

The result: the same ActiveRecord::RecordNotFound from a missing record looks like one issue even if it fires from dozens of different user requests. A transient network error in a background job gets grouped instead of creating hundreds of separate entries. Source maps can still make a minified frontend crash easier to inspect, but they are applied after grouping and never move a report between issues.

This mirrors the practical model described in Sentry's issue grouping documentation: use explicit fingerprints when present, prefer stack trace information when available, then fall back to exception and message data. Telebugs keeps that workflow focused on production error tracking instead of asking you to run a broad observability platform.

Stable grouping defaults

Telebugs uses one internal grouping algorithm for every installation and project. There is no algorithm selector or collection of permanent grouping knobs. The algorithm is versioned internally so upgrades can improve future decisions without silently rewriting historical reports.

Default grouping uses a fixed evidence order:

  1. The oldest causal exception with a useful stack.
  2. A crashed thread, then the current thread, then the final thread with a useful stack.
  3. The causal exception type and normalized value.
  4. An SDK message template, then a normalized formatted message.
  5. A per-occurrence key when the event contains no trustworthy grouping evidence.

For stack-based errors, Telebugs includes the event platform and causal exception type, preserves frame order, and uses at most the final 50 selected frames. Stable filenames, functions, modules, and source context matter; line and column shifts are ignored when those stronger signals are available. URL origins, query strings, fragments, deploy-release directories, and filename content hashes are normalized. Otherwise anonymous frames—including generated frames without stable function or source-context evidence—keep their line, column, or address so unrelated failures are not merged.

When no useful stack exists, Telebugs uses the causal exception type and a normalized value, then an SDK message template or normalized formatted message. Occurrence values such as request IDs, UUIDs, timestamps, IP addresses, emails, memory addresses, long hashes, URL query values, numeric path segments, and ordinary instance numbers do not create a new issue. Semantic values such as HTTP status, SQLSTATE, errno, signal, port, exit code, and version numbers remain meaningful grouping evidence.

Release, environment, server, request URL, user, and tag metadata do not change a stack-based grouping key. Releases remain valuable debugging context, and a new report still follows normal Telebugs behavior for reopening, notifications, mute rules, severity, and ownership.

When error grouping goes wrong

Most grouping problems fall into one of two categories: too many groups, or groups that are too broad.

Symptom Common cause What to do
Many nearly identical issues Dynamic IDs, paths, tenants, or messages changing the grouping signal. Send a custom fingerprint that keeps the stable part and removes noisy values.
Unrelated errors in one issue A fingerprint that is too broad, or log messages without enough stack context. Add more specific fingerprint parts such as action, route, job, or exception type.
Frontend issues change after every deploy Minified JavaScript or changed bundle positions without stable function information. Use a stable custom fingerprint when generated locations should represent one problem. Source maps improve the displayed trace but do not regroup reports.
One-off refactor creates duplicate issues The stack trace changed even though the underlying bug is the same. Merge the related groups in the Telebugs UI, API, or MCP tools.

The goal is not perfect mathematical clustering. The goal is a reliable debugging workflow where each issue represents one underlying problem often enough that engineers trust the list.

Custom fingerprinting

Sometimes the defaults are not quite right for your codebase. Fingerprinting is the cleanest way to tell an error tracker, "these events belong together" or "split this broad error by a stable business dimension."

Custom fingerprints via the SDK

You can tell the Sentry-compatible SDK exactly how to group an error by passing a fingerprint array when capturing it. A non-empty fingerprint without an exact {{ default }} component replaces default grouping, so events with the same ordered components share an issue even when their stacks or platforms differ. 

# Ruby / Rails example
Sentry.capture_exception(e, fingerprint: ["payment-failure", current_action])

# Python / Django example
sentry_sdk.capture_exception(e, fingerprint=["checkout-error", str(user_id)])

// JavaScript / TypeScript example
Sentry.captureException(error, {
  fingerprint: ["checkout-error", routeName]
});

This is useful for business-level grouping: all payment failures, all checkout errors for one route, all validation errors from one form, or one noisy integration grouped by provider. It works through the Sentry SDK payload, so it fits naturally into a migration from Sentry to Telebugs.

Use stable values in fingerprints. A route name, job name, provider name, or exception type is usually helpful. A user ID, order ID, timestamp, or request UUID often creates too many groups unless that split is exactly what you want.

Refining default grouping

A custom fingerprint normally replaces default grouping. To keep the complete Telebugs default and add one stable dimension, include an exact {{ default }} component: 

Sentry.capture_exception(e, fingerprint: ["{{ default }}", provider_name])

Only an exact component expands. A fingerprint containing only ["{{ default }}"] is identical to ordinary default grouping. Text such as prefix-{{ default }} remains literal. Telebugs accepts an ordered array of strings and also accepts a scalar string as one component. Component values, whitespace, order, and boundaries are preserved, so ["a|b"] is not the same fingerprint as ["a", "b"].

Fingerprints are limited to 32 components, 1 KiB per component, and 8 KiB in total, measured as UTF-8 bytes. An absent or null fingerprint, an empty string or array, and otherwise invalid fingerprints safely use default grouping instead. These limits keep ingestion predictable on a small self-hosted server.

Manual merging in the UI

When similar issues end up as separate groups (common after a refactor or when stack traces differ slightly), you can merge them directly in the Telebugs interface:

  1. Open the main (target) issue.
  2. Click Merge.
  3. Paste the URLs of the groups you want to combine.
  4. Confirm.

Telebugs retargets known grouping keys and retains legacy source aliases so future matches continue to land in the combined issue. The action is irreversible, so use it when you're confident the issues represent the same underlying problem.

Grouping details are also visible on each issue so you can understand exactly why Telebugs decided two reports belong together (or did not). This transparency helps when tuning custom fingerprints, reviewing merged groups, and explaining why an issue appears the way it does.

Grouping through upgrades

Grouping upgrades are forward-looking. Telebugs does not backfill grouping keys, rewrite historical reports, or automatically regroup old issues. When a new report matches an existing issue through the previous fingerprint, Telebugs records a compatibility key lazily and keeps the canonical issue's history. If the old fingerprint had combined two different problems, the second v2 signature becomes a new future-only issue; past reports stay where they are.

Manual merges remain durable aliases: future reports matching any merged source go to the final target. The grouping details dialog shows a read-only label—v1 for untouched legacy issues, v2 for issues created by the current algorithm, and v1 + v2 compatibility for legacy issues reused after an upgrade. There are no algorithm controls.

Grouping across the stack

Because Telebugs accepts Sentry SDK error events, the same grouping workflow applies whether the error comes from:

One consistent grouping workflow across projects matters when a team owns several apps. You can keep the same triage habits: open the issue, review reports, inspect stack frames and breadcrumbs, check release metadata, assign an owner, add notes, and resolve when the fix ships.

Grouping details for AI debugging

Grouped issues are also a better unit of work for AI coding tools. A raw stream of individual events is noisy; one issue with representative reports, stack traces, breadcrumbs, notes, releases, and affected context gives the tool something concrete to investigate.

Telebugs supports MCP error tracking, so approved AI tools can inspect projects, error groups, reports, breadcrumbs, backtraces, notes, and group state through scoped access. Newer Telebugs releases also expose MCP actions for resolving, muting, assigning, and merging error groups when you grant write permissions.

This is not magic debugging, and it does not replace engineering judgment. It simply gives your coding tool structured production context without asking you to paste stack traces into a chat window.

Self-hosted grouping

In broad self-hosted observability stacks, grouping is one feature among many. That can be the right tradeoff for large platform teams, but it is often more than a small product team needs when the core job is production error tracking.

Telebugs keeps grouping close to the rest of the debugging workflow:

  • Issues, reports, backtraces, breadcrumbs, releases, notes, and notifications live in one focused product.
  • Custom fingerprints and manual merge controls let you repair grouping without changing tools.
  • No event quotas mean a noisy bug is a triage problem, not an immediate billing surprise.
  • Low-resource self-hosting keeps the operating surface small.

If you mainly need exceptions, grouping, readable stack traces, release context, notifications, and team workflow, Telebugs is intentionally shaped around that narrower job. For the larger hosting decision, compare it with self-hosted Sentry.

Frequently asked questions

What is error grouping in error tracking?

Error grouping is how an error tracker turns repeated reports from the same underlying bug into one issue. The individual reports are still available, but the triage view stays focused on fixable problems instead of duplicate events.

What is an error fingerprint?

A fingerprint is a stable identifier used to decide which events belong in the same group. It can be generated automatically from the event, or supplied by your code through the Sentry SDK fingerprint field.

Can I use Sentry SDK fingerprints with Telebugs?

Yes. Telebugs accepts Sentry SDK compatible error events, including custom fingerprints sent by the SDK. This lets you keep existing instrumentation when switching the backend to Telebugs.

What if error grouping creates too many duplicate issues?

Look for unstable values such as tenant names, generated paths, or minified stack frames without stable function information. Use a custom fingerprint for stable business-level grouping or manually merge groups that represent the same bug. Source maps improve the displayed trace after ingestion but do not regroup reports.

What if unrelated errors are grouped together?

Make the fingerprint more specific. Add a route, job name, action, provider, exception type, or another stable value that separates the underlying failures without creating a new group for every request.

Does grouping work for JavaScript minified code?

Telebugs groups generated or minified frames conservatively using the evidence available in the received event. Source maps can map those frames back to original source before you inspect the issue, but source-map processing happens after grouping and never moves reports. Use a stable custom fingerprint if bundle positions should share one issue. See the releases and sourcemaps guide for setup.

Can AI tools inspect grouped errors?

Yes, with permission. Telebugs supports MCP, so approved AI tools can inspect projects, error groups, reports, backtraces, breadcrumbs, notes, and group state through scoped access.

Can I turn grouping off?

No. Ungrouped errors are almost never useful at scale. If you truly need every individual report as a separate issue, you can achieve something close with very unique custom fingerprints, but we strongly recommend against it.

How does it compare to Sentry grouping?

Telebugs accepts Sentry SDK compatible error payloads and supports custom fingerprints, including an exact {{ default }} component. It does not claim to reproduce every Sentry grouping mechanism or server-side rule. Telebugs uses one focused internal algorithm for grouped production errors, reports, stack traces, releases, notifications, retention, API access, and MCP.

Ready to stop drowning in duplicate errors?

Review Sentry SDK compatibility, check pricing, or request a private demo. When you are ready, buy Telebugs and start seeing cleaner issues.