feat(express)!: Remove shouldHandleError from setupExpressErrorHandler

MIGRATION.md

@@ -829,6 +829,27 @@ If you prefer to capture errors yourself, set `expressIntegration({ shouldHandle
 
 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`.
 
+The `setupExpressErrorHandler` and `expressErrorHandler` no longer accept a `shouldHandleError` option, and the `ExpressHandlerOptions` type was removed. Set the callback on `expressIntegration()` instead:
+
+```diff
+ Sentry.init({
+-  integrations: [Sentry.expressIntegration()],
++  integrations: [
++    Sentry.expressIntegration({
++      shouldHandleError(error) {
++        return (error.statusCode ?? 500) >= 400;
++      },
++    }),
++  ],
+ });
+
+-Sentry.setupExpressErrorHandler(app, {
+-  shouldHandleError(error) {
+-    return (error.statusCode ?? 500) >= 400;
+-  },
+-});
+```
+
 ### Span name changes
 
 Affected SDKs: All SDKs.
@@ -1241,6 +1262,7 @@ The `idleTimeout`, `finalTimeout` and `childSpanTimeout` options of interaction
 - (AWS Lambda) The deprecated `startTrace` option was removed. It no longer had any effect; to disable tracing, set `tracesSampleRate` to `0`.
 - (AWS Lambda) The deprecated `tryPatchHandler` function was removed. It was no longer used.
 - (Express) The deprecated `patchExpressModule(options)` signature was removed. Use `patchExpressModule(moduleExports, getOptions)` instead.
+- (Express) The `shouldHandleError` option was removed from `setupExpressErrorHandler` and `expressErrorHandler`, along with the `ExpressHandlerOptions` type. Configure it on `expressIntegration()` instead. See [Express: errors are captured automatically](#express-errors-are-captured-automatically).
 - (Fastify) The deprecated `instrumentFastify` and `handleFastifyError` exports were removed. `fastifyIntegration` now instruments Fastify (v3.21–v5) and captures errors on its own, so neither export is needed. See [Fastify: `setupFastifyErrorHandler` is deprecated](#fastify-setupfastifyerrorhandler-is-deprecated).
 - The `@sentry/node-core/light/otlp` entry point was removed, along with its optional `@opentelemetry/exporter-trace-otlp-http` peer dependency. `otlpIntegration` is now exported directly from every server-side SDK, so `Sentry.otlpIntegration()` needs no extra import or install.
 - The `otlpIntegration` options `setupOtlpTracesExporter` and `collectorUrl` were removed, and the integration no longer sets up a span exporter, span processor, or tracer provider. Configure your own exporter and point it at `Sentry.getOtlpTracesEndpoint(dsn)`, or at your collector's URL if you route through one. See [Connecting Sentry to your OpenTelemetry traces](#connecting-sentry-to-your-opentelemetry-traces).

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

@@ -8,17 +8,19 @@ const app = express();
 app.use(cors());
 
 app.get('/test1', (_req, _res) => {
-  throw new Error('error_1');
+  // 4xx errors are skipped by the default predicate
+  const error = new Error('error_1');
+  error.statusCode = 404;
+  throw error;
 });
 
 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',
-});
+// capturer. It has no `shouldHandleError` of its own, so the default predicate applies: 5xx and
+// status-less errors are captured, 3xx/4xx are not.
+Sentry.setupExpressErrorHandler(app);
 
 startExpressServerAndSendPortToRunner(app);

dev-packages/node-integration-tests/suites/express/handle-error/test.ts

@@ -336,14 +336,15 @@ describe('express error handling', () => {
       },
     );
 
-    // Fallback: with `expressIntegration` disabled, the deprecated middleware is the sole capturer and
-    // its own `shouldHandleError` applies (mechanism `auto.middleware.express`).
+    // Fallback: with `expressIntegration` disabled, the deprecated middleware is the sole capturer
+    // (mechanism `auto.middleware.express`). It applies the default predicate — `shouldHandleError`
+    // is configured on `expressIntegration` only.
     createCjsTests(
       __dirname,
       'scenario-setup-error-handler-fallback.mjs',
       'instrument-setup-error-handler.mjs',
       (createRunner, test) => {
-        test('deprecated handler captures with its own shouldHandleError when expressIntegration is disabled', async () => {
+        test('deprecated handler captures with the default predicate when expressIntegration is disabled', async () => {
           const runner = createRunner()
             .expect({
               event: {
@@ -362,9 +363,9 @@ describe('express error handling', () => {
             })
             .start();
 
-          // this error is filtered & ignored
+          // 4xx: skipped by the default predicate
           runner.makeRequest('get', '/test1', { expectError: true });
-          // this error is actually captured
+          // no status: treated as 5xx and captured
           runner.makeRequest('get', '/test2', { expectError: true });
 
           await runner.completed();

packages/core/src/integrations/express/types.ts

@@ -187,15 +187,3 @@ export type ExpressErrorMiddleware = (
   res: ExpressResponse,
   next: (error: MiddlewareError) => void,
 ) => void;
-
-/**
- * @deprecated `expressIntegration()` captures errors automatically; pass `shouldHandleError` to it to
- * customize capture. This type is deprecated and will be removed in the next major version.
- */
-export interface ExpressHandlerOptions {
-  /**
-   * Callback method deciding whether error should be captured and sent to Sentry
-   * @param error Captured middleware error
-   */
-  shouldHandleError?(this: void, error: MiddlewareError): boolean;
-}

packages/core/src/server-exports.ts

@@ -22,7 +22,6 @@ export { safeUnref as _INTERNAL_safeUnref } from './utils/timer';
 export { patchExpressModule } from './integrations/express/index';
 export type {
   ExpressIntegrationOptions,
-  ExpressHandlerOptions,
   ExpressMiddleware,
   ExpressErrorMiddleware,
 } from './integrations/express/types';

packages/server-utils/src/index.ts

@@ -53,7 +53,7 @@ export { vercelAIIntegration } from './integrations/vercel-ai';
 export { expressIntegration } from './integrations/express';
 /* oxlint-disable typescript/no-deprecated -- deprecated Express error-handler exports, kept until the next major */
 export { expressErrorHandler, setupExpressErrorHandler } from './integrations/express/error-handler';
-export type { ExpressHandlerOptions } from './integrations/express/types';
+export type { ExpressIntegrationOptions } from './integrations/express/types';
 /* oxlint-enable typescript/no-deprecated */
 export { firebaseIntegration } from './integrations/firebase';
 

packages/server-utils/src/integrations/express/error-handler.ts

@@ -1,7 +1,7 @@
-import { captureException, getIsolationScope, httpRequestToRequestData } from '@sentry/core';
+import { captureException, getClient, getIsolationScope, httpRequestToRequestData } from '@sentry/core';
 import { isExpressErrorHandled } from './error-handled';
-import type { ExpressHandlerOptions, ExpressRequest, ExpressResponse, MiddlewareError } from './types';
-import { defaultShouldHandleError } from './utils';
+import type { ExpressIntegration, ExpressRequest, ExpressResponse, MiddlewareError } from './types';
+import { INTEGRATION_NAME, shouldCaptureError } from './utils';
 
 type ExpressErrorMiddleware = (
   error: MiddlewareError,
@@ -12,6 +12,10 @@ type ExpressErrorMiddleware = (
 
 type ExpressMiddleware = (request: ExpressRequest, res: ExpressResponse, next: () => void) => void;
 
+function getExpressIntegration(): ExpressIntegration | undefined {
+  return getClient()?.getIntegrationByName<ExpressIntegration>(INTEGRATION_NAME);
+}
+
 /**
  * Set request data on the isolation scope so a captured error carries request context. Mirrors the
  * request handler middleware, which does not run once an error short-circuits the middleware chain.
@@ -30,7 +34,7 @@ function setSDKProcessingMetadata(request: ExpressRequest): void {
  * @deprecated `expressIntegration()` now captures errors automatically. This export is deprecated and
  * will be removed in the next major version.
  */
-export function expressErrorHandler(options?: ExpressHandlerOptions): ExpressErrorMiddleware {
+export function expressErrorHandler(): ExpressErrorMiddleware {
   return function sentryErrorMiddleware(error, request, res, next): void {
     // When an error happens, the request handler middleware does not run, so we set it here too.
     setSDKProcessingMetadata(request);
@@ -45,9 +49,9 @@ export function expressErrorHandler(options?: ExpressHandlerOptions): ExpressErr
       return;
     }
 
-    const shouldHandleError = options?.shouldHandleError || defaultShouldHandleError;
-
-    if (shouldHandleError(error)) {
+    // `shouldHandleError` is configured on `expressIntegration()` only. Without the integration
+    // registered, the default predicate applies.
+    if (shouldCaptureError(getExpressIntegration()?.getShouldHandleError(), error)) {
       const eventId = captureException(error, {
         mechanism: { type: 'auto.middleware.express', handled: false },
       });
@@ -71,20 +75,16 @@ function expressRequestHandler(): ExpressMiddleware {
  * The error handler must be before any other middleware and after all controllers.
  *
  * @param app The Express instance
- * @param options {ExpressHandlerOptions} Configuration options for the handler
  *
  * @deprecated `expressIntegration()` now captures errors automatically, so calling this is no longer
  * necessary. To customize which errors are captured, pass `shouldHandleError` to `expressIntegration()`.
  * This export is deprecated and will be removed in the next major version.
  */
-export function setupExpressErrorHandler(
-  app: {
-    // oxlint-disable-next-line no-explicit-any
-    use: (middleware: any) => unknown;
-  },
-  options?: ExpressHandlerOptions,
-): void {
+export function setupExpressErrorHandler(app: {
+  // oxlint-disable-next-line no-explicit-any
+  use: (middleware: any) => unknown;
+}): void {
   app.use(expressRequestHandler());
   // oxlint-disable-next-line typescript/no-deprecated
-  app.use(expressErrorHandler(options));
+  app.use(expressErrorHandler());
 }

packages/server-utils/src/integrations/express/index.ts

@@ -3,12 +3,9 @@ import type { IntegrationFn } from '@sentry/core';
 import { defineIntegration } from '@sentry/core';
 import { expressModuleNames } from '../../orchestrion/config/express';
 import { invokeOrchestrionInstrumentation } from '../../orchestrion/instrumentation';
-import type { ExpressIntegrationOptions } from './types';
+import type { ExpressIntegration, ExpressIntegrationOptions } from './types';
 import { instrumentExpress } from './instrumentation';
-
-// NOTE: this uses the same name as the OTel integration by design.
-// When enabled, the OTel 'Express' integration is omitted from the default set.
-const INTEGRATION_NAME = 'Express' as const;
+import { INTEGRATION_NAME } from './utils';
 
 const _expressIntegration = ((options: ExpressIntegrationOptions = {}) => {
   return {
@@ -19,7 +16,12 @@ const _expressIntegration = ((options: ExpressIntegrationOptions = {}) => {
         diagnosticsChannel.tracingChannel,
       ]);
     },
-  };
+    // Read by the deprecated `expressErrorHandler`, which captures only when this integration
+    // could not (no orchestrion transform), so both paths use the same callback.
+    getShouldHandleError() {
+      return options.shouldHandleError;
+    },
+  } satisfies ExpressIntegration;
 }) satisfies IntegrationFn;
 
 /**

packages/server-utils/src/integrations/express/instrumentation.ts

@@ -39,7 +39,7 @@ import type {
   MiddlewareError,
   RegistrationChannelContext,
 } from './types';
-import { defaultShouldHandleError } from './utils';
+import { shouldCaptureError } from './utils';
 import { isExpressErrorHandled, markExpressErrorHandled } from './error-handled';
 import { setHttpServerSpanRouteAttribute } from '../../utils/setHttpServerSpanRouteAttribute';
 
@@ -150,11 +150,7 @@ export function captureLayerError(
     markExpressErrorHandled(request);
   }
 
-  if (shouldHandleError === false) {
-    return;
-  }
-
-  if (!(shouldHandleError ?? defaultShouldHandleError)(error as MiddlewareError)) {
+  if (!shouldCaptureError(shouldHandleError, error as MiddlewareError)) {
     return;
   }
 

packages/server-utils/src/integrations/express/types.ts

@@ -1,4 +1,4 @@
-import type { Span } from '@sentry/core';
+import type { Integration, Span } from '@sentry/core';
 
 export type ExpressLayerType = 'router' | 'middleware' | 'request_handler';
 
@@ -73,12 +73,6 @@ export interface MiddlewareError extends Error {
 /** Callback deciding whether an error should be captured; `false` disables capture entirely. */
 export type ExpressShouldHandleError = ((error: MiddlewareError) => boolean) | false;
 
-/** Options for the deprecated `setupExpressErrorHandler` / `expressErrorHandler`. */
-export interface ExpressHandlerOptions {
-  /** Callback deciding whether an error should be captured and sent to Sentry. */
-  shouldHandleError?: (error: MiddlewareError) => boolean;
-}
-
 type IgnoreMatcher = string | RegExp | ((name: string) => boolean);
 export interface ExpressIntegrationOptions {
   /** Ignore specific based on their name */
@@ -113,3 +107,7 @@ export interface ExpressIntegrationOptions {
    */
   shouldHandleError?: ExpressShouldHandleError;
 }
+
+export interface ExpressIntegration extends Integration {
+  getShouldHandleError: () => ExpressShouldHandleError | undefined;
+}

packages/server-utils/src/integrations/express/utils.ts

@@ -1,4 +1,8 @@
-import type { MiddlewareError } from './types';
+import type { ExpressShouldHandleError, MiddlewareError } from './types';
+
+// NOTE: this uses the same name as the OTel integration by design.
+// When enabled, the OTel 'Express' integration is omitted from the default set.
+export const INTEGRATION_NAME = 'Express' as const;
 
 function getStatusCodeFromResponse(error: MiddlewareError): number {
   const statusCode = error.status || error.statusCode || error.status_code || error.output?.statusCode;
@@ -13,3 +17,19 @@ function getStatusCodeFromResponse(error: MiddlewareError): number {
 export function defaultShouldHandleError(error: MiddlewareError): boolean {
   return getStatusCodeFromResponse(error) >= 500;
 }
+
+/**
+ * Apply the configured `shouldHandleError`: `false` turns capture off entirely, a function replaces
+ * the gate, and `undefined` falls back to {@link defaultShouldHandleError}. Both the integration and
+ * the deprecated middleware go through here, so they always agree.
+ */
+export function shouldCaptureError(
+  shouldHandleError: ExpressShouldHandleError | undefined,
+  error: MiddlewareError,
+): boolean {
+  if (shouldHandleError === false) {
+    return false;
+  }
+
+  return (shouldHandleError ?? defaultShouldHandleError)(error);
+}