Connect Koa to Bugsink

When Koa middleware fails, Bugsink shows you the exception, the application frame that raised it, and the HTTP request being handled.

This guide covers the initial setup and Koa’s automatic capture of unhandled middleware errors. You’ll connect an existing application, then make one request fail to confirm that it reaches Bugsink.

To follow along, create a Bugsink project and copy its DSN. The quickstart guide shows where to find it.

Install the SDK

Install the open-source Sentry SDK alongside Koa. Bugsink accepts the Sentry event protocol, so the SDK can send events directly to your project:

npm install --save-exact @sentry/node@11.14.0

Initialize the SDK before Koa

Create an instrumentation module which initializes the SDK from the DSN in the environment:

import * as Sentry from "@sentry/node";


Sentry.init({
  dsn: process.env.SENTRY_DSN,
});

Load it with Node’s --import option before the server module. Initializing later can miss Koa’s framework instrumentation even though explicit capture calls still work:

"scripts": {
    "start": "node --import ./instrument.mjs server.mjs"
  },

Set SENTRY_DSN in the environment where the server runs:

export SENTRY_DSN=https://key@bugsink.example/1

Let errors reach Koa

No Bugsink middleware is required. The SDK attaches its error listener when Koa creates the request callback, while Koa continues to own the HTTP response. The important part is not catching an exception before Koa sees it.

To verify the setup, this middleware throws when a product is missing:

const checkout = context.path.match(/^\/checkout\/([^/]+)$/);
  if (context.method === "GET" && checkout) {
    const sku = decodeURIComponent(checkout[1]);
    const product = inventory.get(sku);
    if (!product) {
      throw new ProductNotFound(`Product ${sku} is not in inventory`);
    }
    context.body = { reserved: product.name };
    return;
  }

Start the application as usual, then request a missing product:

npm start
:::bash
curl http://127.0.0.1:3000/checkout/koa-missing

Koa returns an HTTP 500 response and the SDK reports the exception.

See the error in Bugsink

Open your Bugsink project and select the new ProductNotFound issue. Its event points to the failing middleware line and includes the GET request.

Bugsink preview

That’s it: unhandled Koa middleware errors will now be reported to Bugsink. Your middleware remains ordinary application code, while Bugsink receives its JavaScript stack and request context.

For handled exceptions, messages, tags, structured context, and breadcrumbs, continue with the Node.js guide.