Reporting handled errors

Reporting handled errors allows your application to recover from an error, while still reporting it to BugSnag.

To notify Bugsnag of a handled exception you can call Bugsnag.notify:

  raise 'Something went wrong!'
rescue => e

Sending custom diagnostics

In order to quickly understand and fix some errors, it is often helpful to send additional diagnostic data which is specific to that error. Bugsnag.notify accepts a block which can alter the report before it is sent to BugSnag.

Bugsnag.notify(exception) do |event|
  # Adjust the severity of this error
  event.severity = "warning"

  # Add customer information to this event
  event.add_metadata(:account, {
    name: "Acme Co.",
    paying_customer: true

See the event object below for all available customization options.

The event object


Declare a single feature flag or experiment with variant as an optional second parameter.

event.add_feature_flag('Checkout button color', 'Blue')
event.add_feature_flag('New checkout flow')

For more information, see Feature flags & experiments.


Declare multiple feature flags or experiments.

  ['Checkout button color', 'Blue')'New checkout flow')

For more information, see Feature flags & experiments.


Adds the specified key and value in the specified section, which is shown as a tab on the BugSnag dashboard.

Data can be added key-by-key:

event.add_metadata(:company, :name, 'Acme Co.')

Alternatively a Hash can be added to a section:

event.add_metadata(:company, {
  name: 'Acme Co.',
  country: 'uk'


Call add_tab on an event object to add a tab to the event so that it would appear on your dashboard.

event.add_tab(:user_info, { name: "Bugs Nag" })

The first parameter is the tab name that will appear in the event and the second is the key, value list that will be displayed in the tab.

Deprecated: Use add_metadata instead.


Set the project API key for the event. The API key is normally set in the configuration, but it can be overridden to report to a different API key in some situations.

event.api_key = 'your-api-key-here'

Customize or filter breadcrumbs to be sent with the event. Modified breadcrumbs will not be validated again.

event.breadcrumbs.each { |breadcrumb| breadcrumb.metadata = {} } # Clear the metadata


Remove a single feature flag or experiment.

event.clear_feature_flag('Checkout button color')


Remove all feature flags and experiments.



Removes all the data from the specified section or from a key in the section:

# Remove a single key
event.clear_metadata(:company, :name)

# Remove an entire section


Set the context of the event. This is notionally the location of the error and should be populated automatically. Context is displayed in the dashboard prominently.

event.context = 'billing'


Allows you to read the class, message and stacktrace of each error in this event.

puts "#{event.errors.first.error_class}: #{event.errors.first.error_message}"
puts event.errors.first.stacktrace


Allows you to access and modify the exceptions that will be combined into the event.

puts event.exceptions.first[:message] + ' found!'

Deprecated for reading: Use errors for reading and exceptions for modification.


Sets the grouping hash of the event. All errors with the same grouping hash are grouped together. This is an advanced usage of the library and misusing it will cause your errors not to group properly in your dashboard.

event.grouping_hash = event.exceptions.first[:message] + event.exceptions.first[:errorClass]


Calling ignore! on an event object will prevent it from being sent to BugSnag. This means that you can choose dynamically not to send an error depending on application state or the error itself.

event.ignore! if foo == 'bar'


Provides access to the metadata in the event.

event.ignore! if event.metadata[:sidekiq][:retry_count] < 2


The Exception instance used to create this event

puts event.original_error.message


Removes a tab completely from the event.


Deprecated: Use clear_metadata instead.


Contains data for the active HTTP request, or nil if no request data has been captured.

puts event.request[:url]


Sets the current user information.

event.set_user('1234', '', 'Bugs Nag')

nil can be used as a parameter value to clear the user attribute.


Set the severity of the error. Severity can be error, warning or info.

event.severity = 'error'


Creates a hashed summary of the event. Given keys are :error_class, :severity, and optionally :message.

summary = event.summary
puts "#{summary[:error_class]} occurred with message: #{summary[:message]}"


By default this is true if the event was automatically detected by BugSnag and false if it was reported manually via Bugsnag.notify. See our product pages for more information on handled vs unhandled events.

event.unhandled = true

Changing the unhandled flag for an event will affect how it contributes to your application’s stability score.


Returns the current user information.

puts event.user[:id], event.user[:email], event.user[:name]

You can use metadata to add additional user information to the “user” section.