How to Set Up Sentry Error Monitoring in Node.js

Sentry can capture Node.js application errors and attach stack traces, environment information, release context, and other debugging data. The setup looks simple—install a package and call Sentry.init()—but initialization order matters. If Sentry loads after the modules you want to instrument, automatic instrumentation can be incomplete.

This tutorial uses the current stable @sentry/node package and a minimal Node application. It shows how to keep the DSN outside source code, load Sentry before the rest of the application, send a controlled verification error, confirm that the event reaches the intended Sentry project, and diagnose common setup mistakes.

Last verified: September 10, 2026. At verification time, npm marks @sentry/node 10.74.0 as the latest stable release. Sentry 11.0.0 is still in beta under the next tag. Recheck the package and Sentry migration documentation before publishing or applying these instructions after this date.

What You'll Accomplish

You will:

1. install the current stable Sentry Node.js SDK;
2. create a dedicated instrumentation file;
3. store the DSN outside source control;
4. ensure Sentry initializes before application modules;
5. capture a controlled test exception;
6. verify the event and stack trace in Sentry; and
7. troubleshoot initialization, DSN, process-lifetime, and privacy problems.

Prerequisites

You need:

• a Sentry organization/project configured for Node.js;
• the project's DSN;
• a Node.js runtime supported by the stable Sentry SDK you are installing;
• npm and permission to modify the application's startup command;
• a small Node or Express-style application;
• a safe development or staging environment for verification.

Do not paste a real DSN, authentication token, customer payload, or production secret into public documentation. A Sentry DSN is designed to identify where events are sent, but it should still be managed as configuration rather than hard-coded into reusable example code.

Quick Answer

Install the stable Node SDK with npm install @sentry/node. Create instrument.js (or instrument.mjs for ESM), import @sentry/node, and call Sentry.init({ dsn: process.env.SENTRY_DSN }). Load that instrumentation file before importing Express, HTTP libraries, database clients, or other application modules. For ESM, current package documentation recommends starting Node with node --import ./instrument.mjs app.mjs. Then trigger a controlled Sentry.captureException(new Error("Sentry verification error")), keep the process alive long enough to send it, and confirm that the event appears in the intended project with the expected environment and stack trace.

Step 1: Confirm the Stable SDK Version Before Installing

Sentry's JavaScript SDK changes frequently.

As of September 10, 2026:

• npm lists @sentry/node 10.74.0 as latest;
• npm lists 11.0.0-beta.2 under next; and
• the Sentry repository contains v11 migration work that should not be treated as the stable production API yet.

For a production tutorial, target the stable tag unless you intentionally need a prerelease feature.

To install the current stable package:

npm install @sentry/node

For a reproducible lab tied to this article's verification date, you can pin the version:

npm install @sentry/[email protected]

Before using the pinned command months later, check npm again. A pinned version is useful for reproducibility, not as a recommendation to remain permanently on an old release.

Step 2: Put the DSN in Environment Configuration

Create an environment variable rather than committing the DSN in application source.

For a local shell:

export SENTRY_DSN="<YOUR_SENTRY_DSN>"

Use your deployment platform's secret/configuration system in production.

Do not publish:

https://<PUBLIC_KEY>@<ORG>.ingest.sentry.io/<PROJECT_ID>

in screenshots, tutorials, repositories, or support examples.

Add useful environment identity

Sentry events are easier to interpret when environments are distinct.

For example:

export NODE_ENV="staging"

Then pass the environment to Sentry from configuration.

The exact names you use—production, staging, dev, region names, or deployment rings—should match your deployment model.

Step 3: Create a Sentry Instrumentation File

For CommonJS, create instrument.js:

const Sentry = require("@sentry/node");

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NODE_ENV || "development",
});

For ESM, create instrument.mjs:

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

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NODE_ENV || "development",
});

The most important part is not the filename. It is when the file is loaded.

Sentry's current npm documentation says the SDK should initialize as early as possible and before other modules that need automatic instrumentation.

Step 4: Load Sentry Before the Application

CommonJS approach

At the very top of the entry file:

require("./instrument");

const express = require("express");

The Sentry initialization runs before Express is loaded.

ESM approach

Sentry's current package documentation recommends Node's --import startup option for ESM:

node --import ./instrument.mjs app.mjs

The package documentation notes that this --import approach is available from Node.js 18.19.0 onward.

If you use npm run start, the documented alternative is to set NODE_OPTIONS:

NODE_OPTIONS="--import ./instrument.mjs" npm run start

Recheck the current SDK and Node support matrix before choosing a runtime solely from this example.

Why initialization order matters

Sentry automatic instrumentation needs to hook supported modules while they are loaded.

This ordering is risky:

const express = require("express");
const Sentry = require("@sentry/node");

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

Even if manual captureException() calls work, some automatic instrumentation may be unavailable because Express was imported first.

Step 5: Add a Controlled Error for Verification

Do not wait for a real customer failure to discover whether Sentry works.

In a development or staging application, add a temporary test route.

A minimal Express example:

const express = require("express");
const Sentry = require("@sentry/node");

const app = express();

app.get("/sentry-test", (req, res) => {
  Sentry.captureException(new Error("Sentry verification error"));
  res.status(500).send("Sentry verification error generated");
});

app.listen(3000, () => {
  console.log("Listening on http://localhost:3000");
});

This assumes Sentry was already initialized from the instrumentation file before this application file loaded.

Request the route:

curl -i http://localhost:3000/sentry-test

The route is intentionally explicit: it calls captureException() with a controlled error.

Remove or protect the route after verification. A public endpoint that creates unlimited error events can be abused and can pollute production telemetry.

Step 6: Verify the Error in Sentry

Open the project you configured and locate the new error event.

Confirm:

• the message is Sentry verification error;
• it belongs to the intended project;
• the event timestamp is current;
• the environment matches your configuration;
• the stack trace points to the expected test code; and
• the event is not missing because the DSN points elsewhere.

Do not stop at "an issue exists." Verify that the issue contains enough context to debug a real failure.

Check the event's environment and release context

If your deployment already has reliable release identifiers, add them according to current Sentry guidance. Release context makes regressions easier to relate to deployments.

Do not invent a release identifier. Use the identifier your build/deployment pipeline actually controls.

Step 7: Capture Real Exceptions Without Hiding Them

Manual capture is useful for verification and for errors you intentionally catch.

Example:

try {
  await performOperation();
} catch (error) {
  Sentry.captureException(error);
  throw error;
}

Re-throwing can be important when the application's normal error handling still needs to run.

Do not add captureException() around every function. Use Sentry's automatic/framework integration where appropriate and manually capture errors only when application logic catches them before the framework would report them.

Otherwise you can create duplicate events.

Step 8: Review Privacy Before Sending Production Data

Error monitoring can collect:

• URLs;
• request metadata;
• user identifiers;
• headers;
• stack-local context;
• tags and custom context; and
• values your code explicitly attaches.

Do not attach passwords, API tokens, session secrets, full authentication headers, payment details, or other sensitive fields.

Sentry's data-collection options evolve between major SDK versions. Review the current stable SDK documentation before enabling broad request data or PII collection.

A useful rule is:

collect the minimum context required to diagnose the problem.

More event data is not automatically better debugging.

Verify the Setup

The setup is complete only when:

• the installed package is the intended stable Sentry Node SDK;
• the DSN comes from environment/deployment configuration;
• the instrumentation file runs before application imports;
• a controlled exception reaches the intended Sentry project;
• the event has a useful stack trace;
• the environment metadata is correct;
• production-sensitive fields have been reviewed; and
• the temporary test route is removed or protected.

If any of these fail, do not assume Sentry is production-ready.

Common Problems and Fixes

Problem: No event appears in Sentry

Possible causes:

• SENTRY_DSN is missing;
• the DSN points to another project;
• network egress to Sentry is blocked;
• the process exits before the event is sent;
• the event is filtered; or
• the verification code never executes.

Fix: print only whether the environment variable is present—not its value—then verify network access, project selection, and application logs.

For example:

console.log("SENTRY_DSN configured:", Boolean(process.env.SENTRY_DSN));

Never print the DSN itself into shared logs just for debugging.

Problem: Manual errors work, but automatic framework instrumentation is incomplete

Likely cause: Sentry initialized after Express or another instrumented module loaded.

Fix: move Sentry initialization into a dedicated instrumentation file and load it before application modules. For ESM, use the documented --import startup approach where supported.

Problem: Events appear under the wrong environment

Cause: the environment is missing or inherited from an unexpected deployment variable.

Fix: explicitly map your deployment environment to the Sentry environment option and verify the event metadata after each environment is onboarded.

Problem: The test script exits before an event appears

Cause: a short one-off process can exit before asynchronous delivery completes.

Fix: verify inside a long-running application during initial setup, or use Sentry's current flush/close guidance for short-lived processes. Do not invent arbitrary sleeps as a production reliability mechanism.

Problem: The same error appears more than once

Cause: the framework/SDK captures it automatically and your code also calls captureException().

Fix: remove redundant manual capture unless it adds a distinct, intentional event. Prefer one authoritative capture path.

Problem: Events contain sensitive request data

Cause: default or custom context collection includes fields your privacy/security model should not send.

Fix: review current Sentry data-collection, before-send, and scrubbing settings. Remove or sanitize sensitive values before they leave the application.

Best Practices

Pin versions in reproducible environments

Use lockfiles and controlled dependency upgrades. A tutorial can state the version it verified, while production dependency policy decides how upgrades are rolled out.

Initialize once and early

Centralize Sentry initialization. Multiple scattered Sentry.init() calls make behavior difficult to reason about.

Separate environment and release

Environment answers "where is this running?" Release answers "what version is running?" Both can be useful, but they are not interchangeable.

Keep error verification deterministic

Use a named controlled exception rather than waiting for a random crash. Remove the verification path after onboarding.

Avoid sending secrets

Treat observability output as data that may be copied to tickets, incident systems, or external tools.

Recheck the migration guide before major upgrades

As of this article, v11 is still prerelease. Major Sentry JavaScript SDK upgrades can change instrumentation and OpenTelemetry interoperability.

When This Setup Makes Sense

Use Sentry error monitoring when your main need is application-level failure visibility:

• uncaught/handled exceptions;
• stack traces;
• regression grouping;
• release/environment context; and
• debugging application failures.

It is not a replacement for infrastructure uptime monitoring, host metrics, or log retention.

If you also need request latency and trace structure, continue with the sibling tutorial on Sentry Performance Tracing in Node.js.

FAQ

Which Sentry Node.js version does this tutorial use?

It was verified against @sentry/node 10.74.0 on September 10, 2026, which npm marked as latest. Sentry 11.0.0-beta.2 was still a prerelease under the next tag.

Where should Sentry.init() run in a Node.js app?

As early as possible, before importing modules that Sentry should instrument. The current package README explicitly emphasizes initialization order.

Why does Sentry receive manual errors but miss framework telemetry?

A common reason is that the SDK initialized after the framework was imported. Move initialization into a preloaded instrumentation file.

Should I commit the Sentry DSN to source control?

For reusable and production configuration, prefer environment/deployment configuration. This keeps project-specific settings out of example code and makes rotation/environment separation easier.

Do I need @sentry/tracing?

No for current Sentry Node SDK setup. That old package was removed from the modern JavaScript SDK line. Do not copy legacy @sentry/tracing tutorials into a current Node.js setup.

Conclusion

A dependable Sentry Node.js setup has three properties: the current stable SDK, early initialization, and a verified event path.

Install @sentry/node, load Sentry before application modules, keep the DSN in configuration, trigger a controlled exception, and verify the resulting event in the correct project. Then review privacy and remove the temporary test path.

Once error capture is trustworthy, the next step is to add performance tracing without relying on obsolete @sentry/tracing examples.

References

1. npm — "@sentry/node" — Sentry — https://www.npmjs.com/package/@sentry/node — accessed September 10, 2026; version 10.74.0 marked latest.
2. GitHub — "Official Sentry SDKs for JavaScript" — getsentry/sentry-javascript — https://github.com/getsentry/sentry-javascript — accessed September 10, 2026.
3. GitHub — "Sentry JavaScript SDK migration guide" — getsentry/sentry-javascript — https://github.com/getsentry/sentry-javascript/blob/develop/MIGRATION.md — accessed September 10, 2026.
4. GitHub — "Upgrading from 7.x to 8.x" — getsentry/sentry-javascript — https://github.com/getsentry/sentry-javascript/blob/develop/docs/migration/v7-to-v8.md — accessed September 10, 2026; used to identify removed legacy tracing patterns.