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.0npm 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, });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" },"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/1export 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; }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-missingnpm 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.
ProductNotFound
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.
