Grouping Issues

Have you ever had a set of similar-looking issues like this? Issues Dashboard

Let's first understand how errors and transactions group into an issue. For example, the issue testTypeIssue16 has 18 events that Sentry grouped into an issue because they share the same

fingerprintThe set of characteristics that define an event.

What is a fingerprint? A fingerprint is a way to uniquely identify an event. Sentry sets a fingerprint by default for you. Sentry uses its own built-in grouping algorithms to generate a fingerprint based on information available within the event such as a stack trace, exception, and message. Events with the same fingerprint are grouped together.

Do I need to do anything? No. Sentry automatically generates a fingerprint based on the event type and all available information. If events have the same root cause, they will group into one issue. If you have separate error issues that you'd like to group together, then this guide will show you how.

How do I see the fingerprint? Open an issue, click the JSON link, and find the fingerprint property. If the default grouping was used, you'll see default written there. If a different grouping was used, you'll see the actual fingerprint value itself.

Why are similar looking Issues not grouping together?

If a set of issues in the Issues Stream looks similar, there is something that still differs: in this case it is the stack trace, and therefore the

fingerprintThe set of characteristics that define an event.
. Let's compare two similar looking error issues side-by-side: Issues Dashboard

Notice the only difference is one had function testTypeIssue15 and the other had testTypeIssue14. This means the stack traces are not identical. Sometimes two stack traces are the same function execution path but differ by one frame. This can be due to several things like middleware you've configured, node_modules, the framework itself, or library imports. To have greater control over which stack frames are included or excluded, see Stack Trace Rules.


There are three different approaches for updating how events group into issues. The first approach is for merging together historical issues already created. We'll call this Merging Similar Issues. The second is for setting rules so next incoming issues will get grouped together. We'll call this Fingerprint Rules. The third is SDK Side Fingerprinting. The difference between SDK side and Server side is the data elements on the exception and stack traces which you can use for matching issues.

In Merging Similar Issues we'll see how historical issues can be merged together. No settings or configuration are required to do this.

In Fingerprint Rules we'll see how to set rules for new incoming issues of our choice to get grouped together by. This will not affect historical issues.

More on SDK Side Fingerprinting here.

Merging Similar Issues

This is for merging similar issues and will not auto merge the next occurrence of this issue coming in.

Before merge Before Merge

After merge, we see that testTypeIssue7 and testTypeIssue8 were merged together. After Merge

You can also do this from inside a single issue. Click the Similar Issues tab Similar Issues

Warning: Future issues will get added to the merged set only if they match one of the stack traces in the merged set.

If you'd like to unmerge issues, you can go to the Issue Details page and click the “Merged Issues” tab. You will see the fingerprints that have been merged into that issue. Select the appropriate checkbox(es) and click “Unmerge”.

Fingerprint Rules

Here's an overview of what we'll do using Fingerprint Rules

  1. Identify the match logic for grouping issues together. We'll use either the error's type or message
  2. Set the match logic and its
    fingerprintThe set of characteristics that define an event.
    for it, in your Project's Settings.

1. Identify Match Logic

Let's say you want the following 2 issues to group together: ConnectionTimeouts

You can do it based on the type as in: ConnectionTimeoutType

Or you can do it based on the message as in any value after the word host: ConnectionTimeoutMessage

2. Implement

Here's how to set the match based on the error type in [Project] > Settings > Issue Grouping > Fingerprint Rules: ConnectionTimeoutTypeExample

Now, all events coming in with ConnectTimeout will get a

fingerprintThe set of characteristics that define an event.
of connect-timeout-type and will get grouped into a single issue. This only applies to future events coming in. Each event for this issue could have a different stack trace, but stack trace is no longer used as the default grouping rule.

Here's how to set the match based on the error message where you want to include all hosts.


You could also do this based on the file path of the erroring function, or on the function name itself. See Fingerprint Rules.

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) to suggesting an update ("yeah, this would be better").