Error grouping

Learn about how and why events are grouped into errors.

BugSnag aims to group instances of the same event together to give you a clear view of which issues are having the biggest impact on your users whilst minimizing unnecessary noise.

In most cases the default grouping achieves this but if you would like to change the grouping behavior, BugSnag provides a range of options as described below.

Grouping reasons

The reason an error is grouped is displayed on the error view. The error may have been subject to either default or custom grouping. Custom grouping allows you to override the default grouping algorithm for errors in your project.

Grouping reason

Default grouping

Top in-project stack frame

Grouped with other events sharing the same error class, file and line number of the top in-project stack frame of the innermost exception.

On most platforms the BugSnag notifier will automatically detect in-project stack frames, but sometimes additional configuration is required to set the root directory of your project. See the docs for your platform.

Top in-project stack frame code

Grouped with other events where the top in-project stack frame of the innermost exception originates from the same section of code and has the same error class.

This algorithm is available for Node.js, PHP, Python, and Ruby projects where sendCode is enabled, and for JavaScript errors in React Native projects.

On most platforms the BugSnag notifier will automatically detect in-project stack frames, but sometimes additional configuration is required to set the root directory of your project. See the docs for your platform.

Surrounding code (JavaScript only)

Grouped with other events originating from the same point in the code.

Method, file and line number (JavaScript only)

Grouped with other events originating from the same method, file and line number.

Script tag line (JavaScript only)

Grouped with other events caused from the same page location.

Script tag (JavaScript only)

Grouped with other events caused from the same script tag. This is used when no information is available about where the error occurred within the script.

Error class (JavaScript eval only)

Grouped with other events with the same error class when the script was evaluated using eval().

Line number (JavaScript only)

Grouped with other events sharing the same line number when the error is generated from a web worker.

Custom grouping

Custom grouping provides a mechanism to override the default grouping algorithm for selected errors in your project.

Error class

Grouped with other events originating from the same error class of the innermost exception. The error classes can be configured in Project settings > Group by error class.

This can be used to group certain errors that may occur from many different parts of your application. For example a database outage may generate DatabaseConnectionErrors from every location that you access the database, but they are all caused by the same issue.

Error context

Grouped with other events sharing the same context that occur in any of the named error classes configured for the project. The error classes can be configured in Project settings > Group by error context.

This can be used to group errors with the same cause that originate from the same part of your application. For example you may know that TimeoutErrors originating from one part of your application (one context) will all have the same cause.

Custom grouping hash

Grouped with other events sharing the same grouping hash. The grouping hash is set by configuring the BugSnag notifier in your code. For specific instructions for configuring the grouping hash please see the documentation for your platform.

Using a custom grouping hash is for advanced users only and can be useful if you want fine-grained control over how errors are grouped.

Updating default grouping

Updating your project to the latest grouping algorithm will improve the way that events with the same root cause are grouped together. You can update the grouping algorithm in Project settings > Default grouping.

Updates are released to make improvements to the grouping algorithm, but they are not automatically applied because they can lead to changes in the way that existing errors are grouped. It is always recommended that you update to the latest grouping algorithm when it is available.

The updated algorithm will only be applied to events received after updating, meaning you may see some new error groupings. Once you have updated to the latest grouping algorithm, you cannot revert the change.

Update default grouping