feat(node): Capture Express errors automatically via expressIntegration

MIGRATION.md

@@ -819,6 +819,16 @@ Affected SDKs: All server-side SDKs.
 
 The LangGraph instrumentation no longer emits `gen_ai.create_agent` spans when a graph is compiled. `gen_ai.invoke_agent` and `gen_ai.execute_tool` spans are unaffected. If you reference `create_agent` spans in dashboards or alerts, update them accordingly.
 
+### Express: errors are captured automatically
+
+Affected SDKs: All server-side SDKs that support Express.
+
+`expressIntegration()` now captures errors thrown from your route handlers automatically, so calling `setupExpressErrorHandler(app)` is no longer necessary — the call can be removed. It is deprecated and will be removed in the next major version. To customize which errors are captured, pass `shouldHandleError` to `expressIntegration()` (by default, 5xx errors and errors without a resolvable status are captured, while 3xx/4xx errors are not).
+
+If you prefer to capture errors yourself, set `expressIntegration({ shouldHandleError: false })` to opt out of automatic capture entirely, and call `Sentry.captureException` from your own error-handling middleware.
+
+The `expressErrorHandler` and `patchExpressModule` exports are deprecated for the same reason and will be removed in the next major version. The export of `expressErrorHandler` and `setupExpressErrorHandler` is moved from `@sentry/core` to `@sentry/server-utils`.
+
 ### Span name changes
 
 Affected SDKs: All SDKs.

dev-packages/e2e-tests/test-applications/node-express-esm-loader/src/app.mjs

@@ -42,8 +42,6 @@ app.get('/test-error', function (req, res) {
   }, 100);
 });
 
-Sentry.setupExpressErrorHandler(app);
-
 app.use(function onError(err, req, res, next) {
   // The error id is attached to `res.sentry` to be returned
   // and optionally displayed to the user for support.

dev-packages/e2e-tests/test-applications/node-express-esm-without-loader/src/app.mjs

@@ -32,8 +32,6 @@ app.get('/test-error', function (req, res) {
   }, 100);
 });
 
-Sentry.setupExpressErrorHandler(app);
-
 app.use(function onError(err, req, res, next) {
   // The error id is attached to `res.sentry` to be returned
   // and optionally displayed to the user for support.

dev-packages/e2e-tests/test-applications/node-express-mcp-v2/src/app.ts

@@ -12,8 +12,6 @@ app.get('/test-success', function (_req, res) {
   res.send({ version: 'v1' });
 });
 
-Sentry.setupExpressErrorHandler(app);
-
 app.listen(port, () => {
   console.log(`Example app listening on port ${port}`);
 });

dev-packages/e2e-tests/test-applications/node-express-streaming/src/app.ts

@@ -97,8 +97,6 @@ app.get('/test-local-variables-caught', function (req, res) {
   res.send({ exceptionId, randomVariableToRecord });
 });
 
-Sentry.setupExpressErrorHandler(app);
-
 // @ts-ignore
 app.use(function onError(err, req, res, next) {
   // The error id is attached to `res.sentry` to be returned

dev-packages/e2e-tests/test-applications/node-express-streaming/tests/errors.test.ts

@@ -21,7 +21,7 @@ test('Sends correct error event', async ({ baseURL }) => {
   const exception = errorEvent.exception?.values?.[0];
   expect(exception?.value).toBe('This is an exception with id 123');
   expect(exception?.mechanism).toEqual({
-    type: 'auto.middleware.express',
+    type: 'auto.http.express',
     handled: false,
   });
 
@@ -37,6 +37,7 @@ test('Sends correct error event', async ({ baseURL }) => {
   expect(errorEvent.contexts?.trace).toEqual({
     trace_id: expect.stringMatching(/[a-f0-9]{32}/),
     span_id: expect.stringMatching(/[a-f0-9]{16}/),
+    parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
   });
 
   // The error is attached to the same trace as the streamed request spans, and to a

dev-packages/e2e-tests/test-applications/node-express-v5/src/app.ts

@@ -104,8 +104,6 @@ app.get('/test-local-variables-caught', function (req, res) {
   res.send({ exceptionId, randomVariableToRecord });
 });
 
-Sentry.setupExpressErrorHandler(app);
-
 // @ts-ignore
 app.use(function onError(err, req, res, next) {
   // The error id is attached to `res.sentry` to be returned

dev-packages/e2e-tests/test-applications/node-express-v5/tests/errors.test.ts

@@ -30,6 +30,7 @@ test('Sends correct error event', async ({ baseURL }) => {
   expect(errorEvent.contexts?.trace).toEqual({
     trace_id: expect.stringMatching(/[a-f0-9]{32}/),
     span_id: expect.stringMatching(/[a-f0-9]{16}/),
+    parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
   });
 
   // The error is attached to the same trace as the request transaction, and to a

dev-packages/e2e-tests/test-applications/node-express/src/app.ts

@@ -105,8 +105,6 @@ app.get('/test-local-variables-caught', function (req, res) {
   res.send({ exceptionId, randomVariableToRecord });
 });
 
-Sentry.setupExpressErrorHandler(app);
-
 // @ts-ignore
 app.use(function onError(err, req, res, next) {
   // The error id is attached to `res.sentry` to be returned

dev-packages/e2e-tests/test-applications/node-express/tests/errors.test.ts

@@ -19,7 +19,7 @@ test('Sends correct error event', async ({ baseURL }) => {
   const exception = errorEvent.exception?.values?.[0];
   expect(exception?.value).toBe('This is an exception with id 123');
   expect(exception?.mechanism).toEqual({
-    type: 'auto.middleware.express',
+    type: 'auto.http.express',
     handled: false,
   });
 
@@ -35,6 +35,7 @@ test('Sends correct error event', async ({ baseURL }) => {
   expect(errorEvent.contexts?.trace).toEqual({
     trace_id: expect.stringMatching(/[a-f0-9]{32}/),
     span_id: expect.stringMatching(/[a-f0-9]{16}/),
+    parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
   });
 
   // The error is attached to the same trace as the request transaction, and to a

dev-packages/e2e-tests/test-applications/tsx-express/src/app.ts

@@ -74,8 +74,6 @@ app.get('/test-local-variables-caught', function (req, res) {
   res.send({ exceptionId, randomVariableToRecord });
 });
 
-Sentry.setupExpressErrorHandler(app);
-
 // @ts-ignore
 app.use(function onError(err, req, res, next) {
   // The error id is attached to `res.sentry` to be returned

dev-packages/e2e-tests/test-applications/tsx-express/tests/errors.test.ts

@@ -30,6 +30,7 @@ test('Sends correct error event', async ({ baseURL }) => {
   expect(errorEvent.contexts?.trace).toEqual({
     trace_id: expect.stringMatching(/[a-f0-9]{32}/),
     span_id: expect.stringMatching(/[a-f0-9]{16}/),
+    parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
   });
 
   // The error is attached to the same trace as the request transaction, and to a

dev-packages/node-integration-tests/suites/esm/warn-esm/server.js

@@ -17,6 +17,4 @@ app.get('/test/success', (req, res) => {
   res.send({ response: 'response 3' });
 });
 
-Sentry.setupExpressErrorHandler(app);
-
 startExpressServerAndSendPortToRunner(app);

dev-packages/node-integration-tests/suites/esm/warn-esm/server.mjs

@@ -15,6 +15,4 @@ app.get('/test/success', (req, res) => {
   res.send({ response: 'response 3' });
 });
 
-Sentry.setupExpressErrorHandler(app);
-
 startExpressServerAndSendPortToRunner(app);

dev-packages/node-integration-tests/suites/express/handle-error/instrument-no-tracing.mjs

@@ -6,4 +6,7 @@ Sentry.init({
   dsn: 'https://public@dsn.ingest.sentry.io/1337',
   release: '1.0',
   transport: loggingTransport,
+  // With tracing off, `expressIntegration()` is not a default integration, so opt in explicitly to
+  // get automatic error capture.
+  integrations: [Sentry.expressIntegration()],
 });

dev-packages/node-integration-tests/suites/express/handle-error/instrument-setup-error-handler.mjs

@@ -0,0 +1,13 @@
+import * as Sentry from '@sentry/node';
+import { loggingTransport } from '@sentry-internal/node-integration-tests';
+
+// Disable the channel-based `expressIntegration()` so the deprecated `setupExpressErrorHandler`
+// middleware is the sole error capturer (mechanism `auto.middleware.express`) — the fallback for
+// setups where the channel-based auto capture is unavailable.
+Sentry.init({
+  traceLifecycle: 'static',
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  release: '1.0',
+  transport: loggingTransport,
+  integrations: integrations => integrations.filter(integration => integration.name !== 'Express'),
+});

dev-packages/node-integration-tests/suites/express/handle-error/instrument-should-handle-error.mjs

@@ -0,0 +1,16 @@
+import * as Sentry from '@sentry/node';
+import { loggingTransport } from '@sentry-internal/node-integration-tests';
+
+Sentry.init({
+  traceLifecycle: 'static',
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  release: '1.0',
+  transport: loggingTransport,
+  integrations: [
+    Sentry.expressIntegration({
+      shouldHandleError: error => {
+        return error.message === 'error_2';
+      },
+    }),
+  ],
+});

dev-packages/node-integration-tests/suites/express/handle-error/scenario-setup-error-handler-fallback.mjs

@@ -0,0 +1,24 @@
+import * as Sentry from '@sentry/node';
+import { startExpressServerAndSendPortToRunner } from '@sentry-internal/node-integration-tests';
+import cors from 'cors';
+import express from 'express';
+
+const app = express();
+
+app.use(cors());
+
+app.get('/test1', (_req, _res) => {
+  throw new Error('error_1');
+});
+
+app.get('/test2', (_req, _res) => {
+  throw new Error('error_2');
+});
+
+// With `expressIntegration` disabled (see the instrument file), the deprecated middleware is the sole
+// capturer and its own `shouldHandleError` applies.
+Sentry.setupExpressErrorHandler(app, {
+  shouldHandleError: error => error.message === 'error_2',
+});
+
+startExpressServerAndSendPortToRunner(app);

dev-packages/node-integration-tests/suites/express/handle-error/scenario-setup-error-handler.mjs

@@ -0,0 +1,24 @@
+import * as Sentry from '@sentry/node';
+import { startExpressServerAndSendPortToRunner } from '@sentry-internal/node-integration-tests';
+import cors from 'cors';
+import express from 'express';
+
+const app = express();
+
+app.use(cors());
+
+app.get('/test1', (_req, _res) => {
+  throw new Error('error_1');
+});
+
+app.get('/test2', (_req, _res) => {
+  throw new Error('error_2');
+});
+
+// Deprecated, and here with a permissive (default) predicate that would capture both errors. But the
+// channel-based `expressIntegration` (configured with `shouldHandleError: error_2` in the instrument)
+// takes precedence: it is the single registered handler, so its predicate decides what is captured and
+// this middleware must neither capture `error_1` nor double-capture `error_2`.
+Sentry.setupExpressErrorHandler(app);
+
+startExpressServerAndSendPortToRunner(app);

dev-packages/node-integration-tests/suites/express/handle-error/scenario-should-handle-error.mjs

@@ -1,4 +1,3 @@
-import * as Sentry from '@sentry/node';
 import { startExpressServerAndSendPortToRunner } from '@sentry-internal/node-integration-tests';
 import cors from 'cors';
 import express from 'express';
@@ -15,10 +14,7 @@ app.get('/test2', (_req, _res) => {
   throw new Error('error_2');
 });
 
-Sentry.setupExpressErrorHandler(app, {
-  shouldHandleError: error => {
-    return error.message === 'error_2';
-  },
-});
+// `shouldHandleError` is configured on `expressIntegration` (see the instrument file); no
+// error handler needs to be registered on the app anymore.
 
 startExpressServerAndSendPortToRunner(app);

dev-packages/node-integration-tests/suites/express/handle-error/scenario.mjs

@@ -29,6 +29,4 @@ app.get('/test/withIsolationScope', () => {
   });
 });
 
-Sentry.setupExpressErrorHandler(app);
-
 startExpressServerAndSendPortToRunner(app);