JavaScript integration guide (v3)

Add Bugsnag to your browser-based JavaScript projects to automatically capture and report exceptions in production.

These docs are for a legacy version of Bugsnag JavaScript. See the current version.

Version 3 Installation

Include bugsnag.js from our CDN in the <head> tag of your website, before any other <script> tags.

<script src="//"


You can also host bugsnag.js yourself if you would like to avoid an additional request. Download the latest version from GitHub or use the bugsnag-js npm package and include the bugsnag script in your assets before any other javascripts. See our FAQ for more information on alternate methods of loading bugsnag.js.

Basic configuration

If you did not set the data-apikey attribute in the installation step or are compressing all of your assets, you can manually set Bugsnag.apiKey.

Bugsnag.apiKey = "YOUR-API-KEY-HERE";

Configuring release stages

To distinguish between errors that happen in different stages of the application release process (development, production, etc), set a release stage for each environment.

Use the notifyReleaseStages configuration option if you would like to only send data to us from particular release stages.

React Support

If you are using an earlier version than React 16, Bugsnag will automatically capture and send errors.

React 16+ includes a feature called error boundaries to provide a smoother error handling experience. By following the below setup, errors occurring in the child component subtree of the ErrorBoundary component will be caught and handled by the error boundary.

Note that in development mode errors will be rethrown at error boundaries, which may result in duplicate errors reported to Bugsnag.

By calling Bugsnag.notifyException within componentDidCatch, you can then report these errors to Bugsnag:

class ErrorBoundary extends React.Component {
  componentDidCatch (error, info) {
    Bugsnag.notifyException(error, { react: info })
  render () {
    return this.props.children
    <App />

See the Bugsnag React example for more tips on error handling in React.

TypeScript support

TypeScript type definitions for Bugsnag are available via DefinitelyTyped.

To use, include a line like so:

/// <reference path="bugsnag/bugsnag.d.ts"

Alternately, the definitions can be downloaded from the Bugsnag library source repository.

Reporting unhandled exceptions

After completing installation unhandled exceptions will be automatically reported to your Bugsnag dashboard.

Reporting handled exceptions

Reporting handled exceptions can be accomplished as follows:

try {
    // Some code which might throw an exception
} catch (exception) {

Since many JavaScript exceptions are named simply Error, we also allow you to provide a custom error name when calling notifyException:

try {
    // Some code which might throw an exception
} catch (e) {
    Bugsnag.notifyException(e, "CustomErrorName");

You can also send custom errors to Bugsnag without any exception, by calling Bugsnag.notify:

Bugsnag.notify("ErrorName", "Something bad happened here");

For more information see reporting handled errors.

Sending diagnostic data

Automatically captured diagnostics

Bugsnag will automatically capture the following data for every exception:

  • Request information such as the IP and URL
  • Browser name, version, user agent and locale
  • Operating system
  • Release stage (production, beta, staging, etc)

Custom diagnostics

The metaData field is a nested object in which each root value will be rendered as a tab in a Bugsnag error report. This example would create a tab called “company” in each error report:

Bugsnag.metaData = {
  company: {
    name: "Acme Co.",
    country: "uk"

Custom diagnostics can also be set in a beforeNotify callback if you need to calculate them at the point when an exception happens:

Bugsnag.beforeNotify = function(payload, metaData) {
  metaData.user_analytics = {
    session_length: 1045,
    new_visitor: false

You can also send custom diagnostics with a handled exception. For more information, see Reporting handled errors.

Leaving breadcrumbs

Breadcrumbs allow you to see a log of actions that led up to an error. Error reports automatically include breadcrumbs for the last 25 events which occurred.

Automatically captured breadcrumbs

By default, Bugsnag captures common events as breadcrumbs including:

  • Clicks
  • Errors
  • Console logs, warnings, and errors
  • Page load, hide, and show
  • DOMContentLoaded
  • Pop state
  • History push state and replace state
  • Hash change

For more information or to disable particular classes of automatic breadcrumb generation, see autoBreadcrumbs) in Configuration options.

Attaching custom breadcrumbs

Bugsnag.leaveBreadcrumb("increased volume")

You can also attach additional diagnostic data to breadcrumbs as follows:

Bugsnag.leaveBreadcrumb('increased volume', {
  from: 5,
  to: 11

Note that for breadcrumbs, the metadata object should only be one level deep and the object’s values are limited to 140 characters each.

Identifying users

In order to correlate errors with customer reports, or to see a list of users who experienced each error, it is helpful to capture and display user information on your Bugsnag dashboard. The user property is used to populate the “User” tab of reported errors on your Bugsnag dashboard, and the id property specifically is used to determine the number of users affected by a particular error. Common other fields to include are name and email.

Bugsnag.user = {
    id: 7,
    name: "Conrad Irwin",
    email: ""

Disabling error reporting

If you wish to disable error reporting, you can return false within Bugsnag.beforeNotify. This would allow for users to opt out of sending error reports, for example:

Bugsnag.beforeNotify = function(payload) {
    return false; // no error report will be sent

Tracking releases

Configure your app version to see the release that each error was introduced in.

Then set up a build tool integration to enable linking to code in your source control provider from the releases dashboard, timeline annotations, and stack traces.

Next steps

  • View bugsnag-js, the library powering this integration, on GitHub
  • For bundled or minified JavaScript, ensure we can access your source maps, so that your error reports include the original source code
  • Get support for your questions and feature requests