Node.js Error & Exception Tracking

Typical installation time: 3 minutes

Hi there! You’ve found Honeybadger’s guide to Node.js error and exception tracking. Once installed, Honeybadger will automatically report errors from your Node.js application.

Installation

Source Code • Issues

First, install the npm package:

npm install @honeybadger-io/js --save

Then, require the honeybadger module and configure your API key:

const Honeybadger = require('@honeybadger-io/js');
Honeybadger.configure({
  apiKey: '[ YOUR API KEY HERE ]'
});

By default Honeybadger will be notified automatically of all unhandled errors which crash your node processes. Many applications catch errors, however, so you may want to set up some additional framework integrations.

Express or Connect Framework

Errors which happen in Express or Connect apps can be automatically reported to Honeybadger by installing our middleware.

In order to function properly our middleware must be added before and after your normal app middleware, but before any other error handling middleware:

app.use(Honeybadger.requestHandler); // Use *before* all other app middleware.
// app.use(myMiddleware);
app.use(Honeybadger.errorHandler);  // Use *after* all other app middleware.
// app.use(myErrorMiddleware);

Note: If you use the connect-domain middleware, you do not need to use Honeybadger.requestHandler because they are essentially the same.

AWS Lambda

Honeybadger can automatically report errors which happen on AWS Lambda:

// Your handler function.
function handler(event, context) {
  console.log('Event:', event);
  console.log('Context:', context);
  throw(new Error('Something went wrong.'));
  console.log("Shouldn't make it here.");
}

// Build and export the function.
exports.handler = Honeybadger.lambdaHandler(handler);

Check out our example Lambda project for a complete example.

Reporting Errors

Honeybadger reports unhandled exceptions by default. You can also manually notify Honeybadger of errors and other events in your application code:

try {
  // ...error producing code...
} catch(error) {
  Honeybadger.notify(error);
}

See the full documentation for more options.

Identifying Users

Honeybadger can track what users have encountered each error. To identify the current user in error reports, add a user identifier and/or email address with Honeybadger.setContext:

Honeybadger.setContext({
  user_id: 123,
  user_email: 'user@example.com'
});

Tracking Deploys

Honeybadger can also keep track of application deployments, and link errors to the version which the error occurred in. Here’s a simple curl script to record a deployment:

HONEYBADGER_ENV="production" \
HONEYBADGER_REVISION="git SHA/project version" \
HONEYBADGER_API_KEY="project api key" \
  curl -g "https://api.honeybadger.io/v1/deploys?deploy[environment]=$HONEYBADGER_ENV&deploy[local_username]=$USER&deploy[revision]=$HONEYBADGER_REVISION&api_key=$HONEYBADGER_API_KEY"

Be sure that the same revision is also configured in the honeybadger.js library. Read more about deploy tracking in the API docs.

Uncaught Exceptions

Honeybadger’s default uncaught exception handler logs the error and exits the process after notifying Honeybadger of the uncaught exception. You can change the default handler by replacing the afterUncaught config callback with a new handler function. Honeybadger will still be notified before your handler is invoked. Note that it’s important to exit the process cleanly if you replace the handler; see Warning: using ‘uncaughtException’ correctly for additional information.

Examples

Honeybadger.configure({
  afterUncaught: (err) => {
    doSomethingWith(err);
    process.exit(1);
  }
});

Disable Honeybadger’s uncaught error handler

To disable Honeybadger’s handler entirely (restoring Node’s default behavior for uncaught exceptions), use the enableUncaught option when calling Honeybadger.configure for the first time:

Honeybadger.configure({
  apiKey: '[ YOUR API KEY HERE ]'
  enableUncaught: false
});

Sample Application

If you’d like to see the library in action before you integrate it with your apps, check out our sample Node.js/Express application.

You can deploy the sample app to your Heroku account by clicking this button:

Don’t forget to destroy the Heroku app after you’re done so that you aren’t charged for usage.

The code for the sample app is available on Github, in case you’d like to read through it, or run it locally.