Drowning in near-identical alerts? Error grouping and deduplication folds every event that shares a fingerprint into a single issue, so you triage causes instead of occurrences. Here is how the matching works and how to tune it.
Grouping is one building block of error monitoring, and the sections below cover how it works, why it sometimes misfires, and how to adjust it.
| Item | Value |
|---|---|
| Fingerprint | Uniquely identifies an event; same fingerprint, same issue |
| Default signal order | Fingerprint, stack trace, exception, message |
| Ways to change grouping | 4 ways |
| Example issue size | 718 events under one fingerprint |
| Effect of fingerprint and stack trace rules | Future events only |
The figures come from Sentry’s grouping guide and Sentry’s issue grouping reference, used here as a worked example. Documentation changes, so check the source before you rely on them.
What a fingerprint is and how events become one issue
A fingerprint is a way to uniquely identify an event, and every event has one. Events that share a fingerprint are grouped together into an issue.
That is the whole deduplication idea. In Sentry’s documentation, an example issue holds 718 events that were grouped because they share the same fingerprint, as described in the grouping guide. You read one issue instead of 718 separate rows.
By default you do not have to configure anything. The tool generates a fingerprint from information such as the stack trace, the exception type and the message. When events have the same root cause, they land in the same issue.
How default grouping chooses what to compare
The default algorithm checks its signals in a fixed priority order. According to the issue grouping reference, all versions consider the fingerprint first, the stack trace next, then the exception, and finally the message.
- Fingerprint: if one is set explicitly, it wins over everything else.
- Stack trace: when a stack trace is present, grouping is effectively based entirely on it, using only the frames the SDK reports and associates with your application.
- Exception: without a stack trace, the exception type and value are used. This is a lot less reliable because error messages change.
- Message: if nothing else is available, grouping falls back to the message.
Because only application frames count, stack traces that differ only in code unrelated to your application still group together. That is why a change deep inside a framework rarely splits an issue.
Some errors need extra help. Chunk load errors and hydration errors often arrive with varying types, values or messages that would produce separate but similar issues, so Sentry keeps built-in fingerprinting rules for them. A custom rule you write always takes precedence over those built-in ones.
Why similar-looking issues stay separate
If a list of issues looks the same but stays split, something still differs between them. The documentation’s own example points to the function name at the top of the stack trace. Compare the actual data, not the title.
A few situations commonly throw grouping off:
- Minified code: minimized JavaScript source destroys grouping in harmful ways, and the fix is making sure the tool can read your source maps. The sibling guide on source maps error tracking covers that setup.
- Added stack levels: introducing a new level through decorators changes the stack trace, so grouping changes with it. Many SDKs can hide irrelevant frames to handle this.
- Changing messages: grouping by exception depends on type and value, so a message with varying text can fragment an issue.
Some tools also add AI-enhanced grouping on top. In Sentry’s documentation, it compares an embedding of the error message and in-app stack frames against existing errors in the project, and merges a new error into an existing issue when it is semantically similar within a configured threshold.
That system only attempts to group new issues and never splits up issues grouped by fingerprint. If it merges something you want separate, you can unmerge those fingerprints and the system avoids grouping them again.
How do you change the grouping?
If the default grouping already suits you, leave it alone. If you see too many similar groups, or unrelated events lumped together, there are four ways to adjust error grouping, listed here from least to most complex:
- Merge issues: combine issues that already exist. No settings or configuration changes are required.
- Fingerprint rules: set a new fingerprint for incoming events based on matchers in project settings.
- Stack trace rules: control which frames count when grouping rules are applied to incoming events.
- SDK fingerprinting: set the fingerprint on the event in your code before it is sent.
Mind the timing. Fingerprint rules, stack trace rules and SDK fingerprinting affect only how future events are grouped, not existing events or issues. Merging also has a limit: any future event that would have created a new issue will still do so, regardless of similarity.
A fingerprint rule can be as simple as matching on the error type. In the docs example, all ConnectTimeout events get the fingerprint connect-timeout-type and group into a single issue regardless of stack trace, as shown in the grouping guide.
In code, the fingerprint is an array of strings. Including the value {{ default }} adds the normally generated grouping hash, so you can split a default group further, for example by RPC function name or status code. The JavaScript fingerprinting page shows this pattern.
To go the other way, omit {{ default }}. For a generic error such as a database connection failure that has many different stack traces and never groups together, setting a fixed fingerprint overrides the default grouping entirely.
A routine for checking a noisy issue list
When an issue list feels wrong, check the data before you change a rule. This order keeps changes small and reversible:
- Open the issue, click the JSON link and find the fingerprint property. If default grouping was used, you will see {{ default }}.
- Compare a pair of issues that look alike and find what differs, such as the top function or the message.
- Rule out minified code or extra wrapper frames before you write any rule.
- Merge the existing duplicates, then add a rule so future events join them.
- Review the result after new events arrive, and unmerge anything that was lumped together by mistake.
Merging alone cleans up the past but not the future, and a rule alone fixes the future but not the past. Most cleanups use both.
What good grouping does for your alerts
Each issue is a single unit of work, so tighter grouping means fewer items to read and assign. Over-grouping hides distinct bugs, and under-grouping buries you in repeats, so aim for one issue per root cause.
Grouping is only part of the picture, and notification rules matter just as much; see how to reduce alert fatigue for that side of the problem. The matching guide is how to reduce alert fatigue.
Frequently asked questions
What is a fingerprint in error tracking?
Show answer
It is a way to uniquely identify an event. Events with the same fingerprint are grouped together into an issue, and Sentry’s documentation says all events have one.
Does merging issues stop duplicates in the future?
Show answer
No. According to Sentry’s grouping guide, a future event that would have created a new issue will still do so, regardless of similarity. Use a fingerprint rule to change how future events group.
Can I undo a merge?
Show answer
Yes. In Sentry, the Merged Issues view in the Issue Details sidebar lists merged fingerprints, and you can select some and unmerge them.
Will new rules regroup my old issues?
Show answer
No. Fingerprint rules, stack trace rules and SDK fingerprinting affect only future events. Merge existing issues if you want to combine them.
Can AI grouping split an issue that has a fingerprint?
Show answer
No. Per Sentry’s reference, it only attempts to group new issues and never splits up issues that were grouped by fingerprint.
