--- title: Node.js integration guide description: Honeybadger monitors your Node.js applications for errors and exceptions so that you can fix them wicked fast. url: https://docs.honeybadger.io/lib/javascript/integration/node/ --- **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. Heads up! Between callbacks, promises, event emitters, and timers, error-handling in Node.js is a complex and difficult field, but we’re here to help! Our Node.js library tries to catch as many different kinds of errors as possible with minimal configuration; if you encounter problems setting it up or find any gaps, feel free to [open an issue](https://github.com/honeybadger-io/honeybadger-js/issues/new). ## Installation First, install the npm package: ```sh npm install @honeybadger-io/js --save ``` Then, require the honeybadger module and configure your API key: ```javascript 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. ## Framework integrations ### Express and Express-style frameworks Errors which happen in [Express](http://expressjs.com/) or [Connect](https://github.com/senchalabs/connect#readme) apps can be automatically reported to Honeybadger by installing our middleware. The `requestHandler` middleware must be added before your other app middleware, while the `errorHandler` must be added after all app middleware and routes, but before any custom error handling middleware: ```javascript app.use(Honeybadger.requestHandler); // Use *before* all other app middleware. // Any other middleware and routes app.use(myMiddleware); app.get("/", (req, res) => {...}); app.use(Honeybadger.errorHandler); // Use *after* all other app middleware // Your custom error handling middleware app.use(myErrorMiddleware); ``` You can follow a similar pattern for most frameworks which use Express-style middleware: #### Restify ```js const server = restify.createServer(); server.use(Honeybadger.requestHandler); // Other middleware and routes... server.on("restifyError", Honeybadger.errorHandler); ``` #### Sails.js For Sails.js, use `Honeybadger.errorHandler` to report errors from within your [custom`serverError`response](https://sailsjs.com/documentation/concepts/extending-sails/custom-responses). ```js const Honeybadger = require("@honeybadger-io/js"); module.exports = function serverError(optionalData) { if (_.isError(optionalData)) { Honeybadger.errorHandler(optionalData, this.req); return res.status(500).send(optionalData.stack); } }; ``` You should also add the `Honeybadger.requestHandler` at the start of your middleware chain so asynchronous context can be correctly tracked between requests: ```js // in config/http.js module.exports.http = { middleware: { order: [ "honeybadgerContext", // other middleware... ], honeybadgerContext: Honeybadger.requestHandler, }, }; ``` ### Non-Express-style frameworks For frameworks that don’t use Express-style middleware, Honeybadger will still capture unhandled exceptions automatically, but you may need to add a few lines of code to capture other kinds of errors and use the context feature properly. See the section on [Tracking Context](https://docs.honeybadger.io/lib/javascript/integration/node/#tracking-context) below. ### AWS Lambda To automatically report errors which happen in your [AWS Lambda](https://aws.amazon.com/lambda/) functions, wrap your Lambda handlers in `Honeybadger.lambdaHandler()`: ```javascript async function myHandler(event, context) { // ... } exports.handler = Honeybadger.lambdaHandler(myHandler); ``` Check out our [example AWS Lambda project](https://github.com/honeybadger-io/honeybadger-js/tree/master/examples/aws-lambda) for a list of handlers with different settings. ##### Timeout warning If your Lambda function hits its [time limit](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html#w329aad109b7b9), it will get killed by AWS Lambda without completing. Honeybadger can notify you when your function is about time out. By default, this will be when there are only 50 milliseconds left to reach the limit. You can override this with the `timeoutWarningThresholdMs` setting: ```javascript Honeybadger.configure({ timeoutWarningThresholdMs: 1000, }); ``` You can disable the timeout warning with the `reportTimeoutWarning` setting: ```javascript Honeybadger.configure({ reportTimeoutWarning: false, }); ``` To manually report errors in a serverless environment, use `Honeybadger.notifyAsync`. Read more below. ## Manually reporting errors Honeybadger reports unhandled exceptions by default. You can also manually notify Honeybadger of errors and other events in your application code: ```javascript try { // ...error producing code... } catch (error) { Honeybadger.notify(error); } ``` `Honeybadger.notify` implements a *fire-and-forget* approach, which means that you can call the function and continue execution in your application code without waiting for the error to be reported. This is OK for most applications, but in some environments this can cause problems when the execution environment could be terminated before the report is sent to Honeybadger. For this reason, you may use `Honeybadger.notifyAsync` which is a promise-based implementation of `notify` and will resolve only after the report is sent: ```javascript async function doSomething() { try { // ...error producing code... } catch (error) { await Honeybadger.notifyAsync(error); } } ``` See the [full documentation](https://docs.honeybadger.io/lib/javascript/) for more options. ## Tracking context You can add contextual information to your error reports to make debugging easier: ```javascript Honeybadger.setContext({ query: searchQuery, }); ``` When an error is captured (manually or automatically), the context will be sent along in the error report and displayed in the Context section of the Honeybadger UI. Important In apps like web servers that handle multiple requests at the same time, you need to properly isolate each request’s context. For middleware-based frameworks like Express, this is done automatically when you use the `requestHandler` middleware. For other frameworks, you’ll need to wrap your request and error handlers in `Honeybadger.withRequest()` method and pass in the request object. Here are examples in some popular frameworks: ### Fastify Fastify doesn’t support middleware by default, but you can use the `preHandler` hook instead. You’ll also need to add a custom error handler (and be sure to wrap it in `Honeybadger.withRequest`): ```js fastify.addHook("preHandler", Honeybadger.requestHandler); fastify.setErrorHandler((err, req, reply) => Honeybadger.withRequest(req, () => { Honeybadger.notify(err); reply.send({ message: "error" }); }), ); ``` ### AdonisJS For AdonisJS, you’ll need to do three (easy) steps: * Create a middleware that wraps your request handlers with `withRequest()`). You can generate a middleware with `adonis make:middleware HoneybadgerContext` (v4) or `node ace make:middleware HoneybadgerContext` (v5): app/Middleware/HoneybadgerContext.js ```js // Adonis v5: app/Middleware/HoneybadgerContext.ts class HoneybadgerContext { async handle({ request, response }, next) { await Honeybadger.withRequest(request, next); } } ``` * Register the middleware: ```js // Adonis v4: in start/kernel.js const globalMiddleware = ["App/Middleware/HoneybadgerContext"]; // Adonis v5: in start/kernel.ts Server.middleware.register([() => import("App/Middleware/HoneybadgerContext")]); ``` * In your exception handler’s `report()` method, make sure to use `withRequest()`. (On Adonis v4, you may need to generate an exception handler with `adonis make:ehandler`): app/Exceptions/Handler.js ```js // Adonis v5: app/Exceptions/Handler.ts class ExceptionHandler extends BaseExceptionHandler { // ... async report(error, { request }) { Honeybadger.withRequest(request, () => Honeybadger.notify(error)); } } ``` ### Hapi In Hapi, you’ll need to wrap your request handlers in `withRequest`, as well as add an `onPreResponse` extension to report errors. ```javascript server.route({ method: 'POST', path: '/search', handler: async (request, h) => Honeybadger.withRequest(request, () => { Honeybadger.setContext({ query: request.payload.searchQuery }); return ...; }) }); server.ext('onPreResponse', (request, h) => Honeybadger.withRequest(request, () => { if (!request.response.isBoom) { return h.continue; } Honeybadger.notify(request.response); return h.continue; })); ``` ## 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`: ```javascript Honeybadger.setContext({ user_id: 123, user_email: "user@example.com", }); ``` We’ll surface this info in a special “Affected Users” section in the Honeybadger UI. ## 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: ```sh HONEYBADGER_ENV="production" \ HONEYBADGER_REVISION="$(git rev-parse HEAD)" \ HONEYBADGER_REPOSITORY="$(git config --get remote.origin.url)" \ HONEYBADGER_API_KEY="Your project API key" \ && curl -g "https://api.honeybadger.io/v1/deploys?deploy[environment]=$HONEYBADGER_ENV&deploy[local_username]=$USER&deploy[revision]=$HONEYBADGER_REVISION&deploy[repository]=$HONEYBADGER_REPOSITORY&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](https://docs.honeybadger.io/api/deployments/). ## 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](https://nodejs.org/api/process.html#process_warning_using_uncaughtexception_correctly) for additional information. ### Examples ```javascript 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`: ```javascript Honeybadger.configure({ apiKey: '[ YOUR API KEY HERE ]' enableUncaught: false }); ``` ## Source map support Honeybadger can automatically un-minify your code if you provide a source map along with your minified JavaScript files. See our [Source Map Guide](https://docs.honeybadger.io/lib/javascript/guides/using-source-maps/) for details. Honeybadger also supports Node’s [experimental`--source-map-support`flag](https://nodejs.org/dist/latest-v14.x/docs/api/cli.html#cli_enable_source_maps) as of **version 14+**. If you run `node` with `--source-map-support` (and are generating source maps in your build), your stack traces should be automatically translated *before* they are sent to Honeybadger. ## 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](https://github.com/honeybadger-io/crywolf-node). You can deploy the sample app to your Heroku account by clicking this button: [![Deploy](https://www.herokucdn.com/deploy/button.png)](https://heroku.com/deploy?template=https://github.com/honeybadger-io/crywolf-node) 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](https://github.com/honeybadger-io/crywolf-node), in case you’d like to read through it, or run it locally. --- ## Try Honeybadger for FREE Intelligent logging, error tracking, and Just Enough APM™ in one dev-friendly platform. Find and fix problems before users notice. [Start free trial](https://app.honeybadger.io/users/sign_up) [See plans and pricing](https://www.honeybadger.io/plans/)