Express and Connect integration guide

Add Bugsnag to your Express and Connect applications.


Install Bugsnag using npm:

npm install bugsnag --save

Basic configuration

1. Require Bugsnag in your app

var bugsnag = require("bugsnag");

2. Register the Bugsnag notifier with your API key


3. Install middleware

To ensure that asynchronous errors are routed to the error handler, add the requestHandler middleware to your app as the first middleware:


To ensure that synchronous errors are sent to Bugsnag, add the errorHandler middleware to your app as the first error middleware:


Reporting unhandled errors

Capturing Asynchronous Errors

Bugsnag can automatically capture both synchronous and asynchronous errors in your code if you wrap it in an autoNotify function.

Note: If you are using the bugsnag.requestHandler middleware for Express or Connect, we automatically wrap your requests with autoNotify.

bugsnag.autoNotify(function() {
  // Your code here

Additionally, you can pass options into autoNotify that will be used as default options for the notify call to any errors. See reporting handled errors for available options.

bugsnag.autoNotify({ context: "thisContext" }, function() {
  // Your code here

The autoNotify function creates a Node.js Domain which automatically routes all uncaught errors to Bugsnag.

Capturing Errors in Callback Functions

Many callback functions in Node are called with an error as the first argument. Bugsnag can intercept these errors if you wrap your callback with bugsnag.intercept:

functionWithCallback(bugsnag.intercept(function(argument) {
  // Your code here

If the first argument is non-null, Bugsnag will be automatically notified of the error, and your callback will not be executed. The first argument is never passed to your callback, since it is assumed to be the error argument.

Using Promises

As of v2.0.0, Bugsnag reports process#unhandledRejection events by default. After handling the rejection, Bugsnag will shut down the process (which will eventually be the default behaviour of Node itself).

If you want to do something else when process#unhandledRejection happens, you can set options.autoNotifyUnhandledRejection=false.

Reporting handled errors

To send non-fatal exceptions to Bugsnag, you can pass any Error object or string to the notify method:

bugsnag.notify(new Error("Non-fatal"));

When reporting handled exceptions, it’s often helpful to send us custom diagnostic data or to adjust the severity of particular errors. For more information, see reporting handled errors.

Sending diagnostic data

Bugsnag will automatically capture a full stack trace for every exception. It is often helpful to send us additional application-specific diagnostic data. This will be displayed as additional tabs in the error dashboard.

All errors

You can apply additional metadata for all errors by adding it to the notification in the onBeforeNotify callback:

bugsnag.onBeforeNotify(function (notification) {

    var metaData =[0].metaData;

    // modify meta-data
    metaData.subsystem = { name: "Your subsystem name" };

For more information, see customizing error reports.

Individual errors

You can send additional metadata with an individual error by supplying it as part of the options to the notify call:

bugsnag.notify(new Error("Something went badly wrong"), {
  subsystem: {
    name: "Your subsystem name"

For more information, see reporting handled errors.

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 id can also be set using the userId property in a notify call or onBeforeNotify callback:

bugsnag.notify(new Error("Something went badly wrong"), { userId: "bob-hoskins" });

Additional user data can also be added by setting a user metadata field:

bugsnag.notify(new Error("Something went badly wrong"), {
  user: {
    id: "bob-hoskins",
    name: "Bob Hoskins",
    email: ""

Note: For Express/Connect apps we automatically set the user id to the ip address of the current request.

User data can also be set on a per-request basis using the requestData property. See customizing error reports for details

Session tracking

Bugsnag tracks the number of “sessions” that happen within your application. This allows you to compare stability scores between releases and helps you to understand the quality of your releases.

Sessions are captured and reported by default. This behaviour can be disabled using the autoCaptureSessions configuration option.

Bugsnag will report a session each time a request is processed.

Next steps