AWS Lambda

BugSnag can automatically report unhandled errors and capture useful metadata in AWS Lambda functions.

This documentation is for version 7 of the BugSnag JavaScript 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.


Install and configure @bugsnag/js, then install the AWS Lambda plugin using npm or yarn:

yarn add @bugsnag/plugin-aws-lambda
# or
npm install --save @bugsnag/plugin-aws-lambda


To start BugSnag with the AWS Lambda integration, pass the plugin to Bugsnag.start along with the Koa plugin:

const Bugsnag = require('@bugsnag/js')
const BugsnagPluginAwsLambda = require('@bugsnag/plugin-aws-lambda')
const BugsnagPluginKoa = require('@bugsnag/plugin-koa')

  apiKey: 'YOUR_API_KEY',
  plugins: [BugsnagPluginAwsLambda, BugsnagPluginKoa],
  otherOptions: value

In the part of your application where the Koa server is configured, obtain and use the Koa middleware:

const app = new Koa()
const middleware = Bugsnag.getPlugin('koa')

// This must be the first piece of middleware in the stack.
// It can only capture errors in downstream middleware

/* all other middleware and application routes go here */

// This handles any errors that Koa catches
app.on('error', middleware.errorHandler)

Finally, start handling errors in your Lambda function by wrapping your application with BugSnag’s handler. For example, using the serverless-http library:

const serverless = require('serverless-http')

const bugsnagHandler = Bugsnag.getPlugin('awsLambda').createHandler()

exports.handler = bugsnagHandler(serverless(app))

BugSnag should always be the outermost handler in your application to ensure all errors are captured.

Automatically captured data

BugSnag will automatically capture the Lambda function’s context in the “AWS Lambda Context” tab on every error.

You can remove individual items from context using redactedKeys:

  redactedKeys: ['invokedFunctionArn']

You can also remove the tab entirely:

Bugsnag.clearMetadata('AWS Lambda context')

Session tracking

A session will be reported automatically each time your Lambda function is called.

This behavior can be disabled using the autoTrackSessions configuration option.


The BugSnag AWS Lambda plugin can be configured by passing options to createHandler.


BugSnag will wait for events and sessions to be delivered before allowing the Lambda function to exit. This option can be used to control the maximum amount of time to wait before timing out.

By default, BugSnag will timeout after 2000 milliseconds.

const bugsnagHandler = Bugsnag.getPlugin('awsLambda').createHandler({
  flushTimeoutMs: 5000

If a timeout does occur, BugSnag will log a warning and events & sessions may not be delivered.


BugSnag will send a handled event to your dashboard to notify you of timeouts in a Lambda function, just before a timeout occurs. This option can be used to control the number of milliseconds before a timeout that BugSnag should be notified.

By default, BugSnag will notify 1000 milliseconds before the Lambda timeout.

const bugsnagHandler = Bugsnag.getPlugin('awsLambda').createHandler({
  lambdaTimeoutNotifyMs: 2000

Set this value to 0 to disable the automatic notification.

If this value is too low, BugSnag may not be notified of timeouts because the Lambda function could be stopped before the notification is delivered.