Connect Node.js to Bugsink

When a Node.js application fails, Bugsink gives you the exception, JavaScript stack trace, and context you need to investigate it.

This guide covers the initial setup, other ways to capture errors, and the useful context you can attach to them. You’ll start by connecting an existing application and triggering a deliberate error 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 for Node.js. Bugsink accepts the Sentry event protocol, so the SDK can send events directly to your Bugsink project:

npm install @sentry/node

Configure your DSN

Import and initialize the SDK before the rest of your application. Reading the DSN from the environment keeps it out of source control:

import * as Sentry from "@sentry/node";
:::javascript
function configureErrorReporting() {
  Sentry.init({
    dsn: process.env.SENTRY_DSN,
  });
}

Call configureErrorReporting() at the beginning of normal startup, and set SENTRY_DSN in the environment where the application runs:

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

Send a test error

Temporarily add an exception to a code path you can run:

throw new Error("Bugsink setup check");

Run that code path once. The exception still terminates the request or process normally; the SDK reports it to Bugsink.

See the error in Bugsink

Open your Bugsink project. The new Error issue contains the JavaScript stack trace and points at the line that raised the exception.

Bugsink preview

That’s it: your Node.js application is connected. Remove the deliberate exception. Bugsink will capture future uncaught exceptions and unhandled promise rejections automatically.

Capture other kinds of errors

Unhandled failures arrive automatically. You can also report exceptions your code catches and exceptional conditions that do not have an exception.

Handled exceptions

A handled exception can still be worth investigating. Pass the caught error to captureException() when the application can recover but you want its stack trace and context. Handled Errors explains when this is useful in more depth:

try {
      processOrder(orderId, 0);
    } catch (error) {
      Sentry.captureException(error);
    }

Bugsink preview: handled exception
Bugsink preview

Messages without exceptions

A message creates a Bugsink event without requiring an exception. Use captureMessage() for an exceptional condition such as an unresponsive queue, and pass the severity Bugsink should show. Prefer exceptions when a stack trace from the actual failure is available:

Sentry.captureMessage(`Order queue is not responding [${orderId}]`, "error");

Bugsink preview: captured message
Bugsink preview

For short-lived commands, call await Sentry.flush(5000) before exiting so queued events have time to be sent. Servers normally send them in the background.

Add useful context

An exception tells you what failed; context helps explain why. Context added to the current scope is attached to subsequent events.

Tags

Tags make events searchable by short key/value pairs. Use setTag() for your own component, region, plan, or feature flag. This adds component: orders to later events on the current scope:

Sentry.setTag("component", "orders");

Bugsink preview: component tag
Bugsink preview

Structured context

Structured context adds a named group of details to an event. Use it for values you want to inspect but not search, such as the order or job being processed:

Sentry.setContext("order", { id: orderId, quantity });

Bugsink preview: structured context
Bugsink preview

Breadcrumbs record what happened before an error. Call addBreadcrumb() for steps the SDK cannot know about, such as starting checkout or retrying an external call. The next error includes it:

Sentry.addBreadcrumb({
    category: "order",
    message: "Starting order processing",
    data: { orderId },
    level: "info",
  });

Bugsink preview: breadcrumb
Bugsink preview

JavaScript frameworks

Server and browser integrations capture failures in their normal request or rendering lifecycle and add the relevant context automatically.

React Capture React error-boundary failures with fallback UI and original JSX source context. Vite Capture uncaught browser errors and resolve production frames with uploaded Vite source maps. Next.js Capture browser and App Router failures with original source from uploaded production Webpack maps. Vue Capture Vue component failures with component context and original single-file component source. Angular Capture Angular component failures and resolve production frames to their original TypeScript source. Express Capture unhandled Express route exceptions with their HTTP request and application frame. Astro Capture browser and server route failures with original source from uploaded production maps. NestJS Capture unexpected NestJS request exceptions with their route, HTTP request, and TypeScript frame. SvelteKit Capture browser and server failures, including original Svelte source from uploaded production maps. Nuxt Capture browser and Nitro failures with original source from uploaded production maps. Fastify Capture unhandled Fastify route exceptions with their HTTP request and application frame. Remix Capture browser route-boundary and server loader failures, with original browser source from uploaded production maps. Koa Capture unhandled Koa middleware exceptions with their HTTP request and application frame. Hapi Capture unhandled Hapi route exceptions with their HTTP request and application frame. Connect Capture unhandled Connect middleware exceptions with their HTTP request and application frame.