Skip to content

feat(express)!: Remove shouldHandleError from setupExpressErrorHandler#23732

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
s1gr1d merged 5 commits into from
Aug 31, 2026
Merged

feat(express)!: Remove shouldHandleError from setupExpressErrorHandler#23732

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
90f635f
test(express): Error handler tests
s1gr1d Aug 28, 2026
b05851b
feat(express)!: Remove `shouldHandleError` from `setupExpressErrorHan…
s1gr1d Aug 28, 2026
2385dba
only filter in expressIntegration
s1gr1d Aug 31, 2026
fe1b7ef
small fixes
s1gr1d Aug 31, 2026
021f333
Merge branch 'develop' into sig/express-handleError
s1gr1d Aug 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions MIGRATION.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -863,6 +863,29 @@ 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 Number(error.statusCode ?? 500) >= 400;
+ },
+ }),
+ ],
});

-Sentry.setupExpressErrorHandler(app, {
- shouldHandleError(error) {
- return (error.statusCode ?? 500) >= 400;
- },
-});
```

`setupExpressErrorHandler(app)` keeps working for the time being. It captures 5xx errors and errors without a status, and cannot be filtered in the error handler.

### `onUnhandledRejectionIntegration`: no warning before `Error` rejections in `strict` mode

Affected SDKs: `@sentry/node` and all dependents.
Expand DownExpand Up@@ -1297,6 +1320,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).
Expand Down
12 changes: 7 additions & 5 deletions ...e-integration-tests/suites/express/handle-error/scenario-setup-error-handler-fallback.mjs
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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);
11 changes: 6 additions & 5 deletions dev-packages/node-integration-tests/suites/express/handle-error/test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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: {
Expand All@@ -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();
Expand Down
12 changes: 0 additions & 12 deletions packages/core/src/integrations/express/types.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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;
}
1 change: 0 additions & 1 deletion packages/core/src/server-exports.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -21,7 +21,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';
Expand Down
2 changes: 1 addition & 1 deletion packages/server-utils/src/index.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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 */

@isaacsisaacsAug 30, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think any deprecated items are being pulled in here, are they? It's the one in core that's deprecated, this one isn't.

@s1gr1ds1gr1dAug 31, 2026

Copy link
Copy Markdown
MemberAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Those exports are deprecated as well

export { expressErrorHandler, setupExpressErrorHandler } from './integrations/express/error-handler';
export type { ExpressHandlerOptions } from './integrations/express/types';
export type { ExpressIntegrationOptions } from './integrations/express/types';

@isaacsisaacsAug 30, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a bit minor, but could be confusing. @sentry/core already exports a different ExpressIntegrationOptions (in packages/core/src/server-exports.ts line 23, defined at packages/core/src/integrations/express/types.ts lines 147-153.)

The core version is deprecated, and doesn't have shouldHandleError. This one isn't actually accessible, since it's not re-exported by @sentry/node.

This can certainly be cleaned up in a followup, but I think it would be best to coalesce these into a single type (either defined in core, or here, but not both).

@s1gr1ds1gr1dAug 31, 2026

Copy link
Copy Markdown
MemberAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, this makes sense and can be done in a follow-up 👍

@s1gr1ds1gr1dAug 31, 2026

Copy link
Copy Markdown
MemberAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done here: #23763

/* oxlint-enable typescript/no-deprecated */
export { firebaseIntegration } from './integrations/firebase';

Expand Down
28 changes: 12 additions & 16 deletions packages/server-utils/src/integrations/express/error-handler.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
import { captureException, getIsolationScope, httpRequestToRequestData } from '@sentry/core';
import { isExpressErrorHandled } from './error-handled';
import type { ExpressHandlerOptions, ExpressRequest, ExpressResponse, MiddlewareError } from './types';
import type { ExpressRequest, ExpressResponse, MiddlewareError } from './types';
import { defaultShouldHandleError } from './utils';

type ExpressErrorMiddleware = (
Expand DownExpand Up@@ -28,9 +28,9 @@ function setSDKProcessingMetadata(request: ExpressRequest): void {
* An Express-compatible error handler, used by {@link setupExpressErrorHandler}.
*
* @deprecated `expressIntegration()` now captures errors automatically. This export is deprecated and
* will be removed in the next major version.
* will be removed in the next major version. Migrate to the `expressIntegration` to filter with `shouldHandleError`.
*/
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);
Expand All@@ -45,9 +45,9 @@ export function expressErrorHandler(options?: ExpressHandlerOptions): ExpressErr
return;
}

const shouldHandleError = options?.shouldHandleError || defaultShouldHandleError;

if (shouldHandleError(error)) {
// `shouldHandleError` is an `expressIntegration()` feature and is deliberately not honoured here:
// this path exists to keep capturing errors, not to filter them.
if (defaultShouldHandleError(error)) {
const eventId = captureException(error, {
mechanism: { type: 'auto.middleware.express', handled: false },
});
Expand All@@ -71,20 +71,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
* @deprecated `expressIntegration()` now captures errors automatically, so calling this error handler 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());
}
6 changes: 0 additions & 6 deletions packages/server-utils/src/integrations/express/types.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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 */
Expand Down
Loading