Reporting handled exceptions

In order to quickly understand and fix errors, it is often helpful to send exceptions that have been handled by your application to BugSnag, with additional diagnostic data that is specific to the error.

This documentation is for version 5+ of the BugSnag Android notifier. If you are using older versions, we recommend upgrading to the latest release using our Upgrade guide. Documentation for the previous release can be found on our legacy pages.

Basic usage

If you would like to send handled exceptions to BugSnag, you can pass any Throwable object to the Bugsnag.notify method.

try {
    // Some potentially crashy code
} catch (Throwable e) {
    Bugsnag.notify(e);
}

try {
    // Some potentially crashy code
} catch (e: Throwable) {
    Bugsnag.notify(e)
}

This will create and send a report for a “handled” error, with the default severity “warning”.

When reporting errors from C or C++ code, invoke bugsnag_notify_env with a name, message and severity.

if (strlen(username) == 0) {
    // report failure to BugSnag
    bugsnag_notify_env(env, "Validation Error", "No name specified", BSG_SEVERITY_WARN);
}

Customizing diagnostic data

You can send handled exceptions with diagnostic data or other customizations by passing an OnErrorCallback as an argument to notify.

The callback receives an Event object as a parameter which can be used to add or amend the data sent to your BugSnag dashboard. You can also return false from the callback to prevent the event being sent at all:

try {
    // Some potentially crashy code
} catch (Throwable exception) {
    Bugsnag.notify(exception, new OnErrorCallback() {
        @Override
        public boolean onError(Event event) {
            // Add extra information
            event.addMetadata("account", "name", "Acme Co.");
            event.addMetadata("account", "paying_customer", true);

            // Increase severity
            event.setSeverity(Severity.ERROR);

            // Return `false` if you'd like to stop this error being reported
            return true;
        }
    });
}

try {
    // Some potentially crashy code
} catch (e: Throwable) {
    Bugsnag.notify(exception, { event ->
        // Add extra information
        event.addMetadata("account", "name", "Acme Co.")
        event.addMetadata("account", "paying_customer", true)

        // Increase severity
        event.severity = Severity.ERROR

        // Return `false` if you'd like to stop this error being reported
        true
    })
}

Native callbacks are not available for handled errors for C/C++, however notify calls from the NDK layer trigger OnErrorCallback functions in Java/Kotlin and so can be used to customize the data or discard events. Additionally, global metadata added to the Bugsnag client is synchronized with the NDK layer and so will also appear in native reports for handled errors.

See Customizing error reports for more information about the properties and methods available in an Event object.