Interactive v11 Migration Guide for Nest.js
Migrate from Sentry JavaScript SDK 10.x to 11.x with an interactive checklist for your platform.
Use curl to download and read https://docs.sentry.io/platforms/javascript/guides/nestjs/migration/v10-to-v11.md before making changes. Upgrade this project from Sentry JavaScript SDK v10 to v11. Inspect the project's Sentry packages, configuration, runtime, and framework versions, then apply every migration step that applies. Preserve the intended data collection behavior when migrating sendDefaultPii to dataCollection. Use the project's package manager to update dependencies and its existing checks to verify the migration. Summarize the changes and any remaining manual steps.Version 11 of the Sentry JavaScript SDK focuses on better OpenTelemetry interoperability, more flexible instrumentation, and better out-of-the-box defaults. It raises the minimum versions of Node.js, TypeScript, and several frameworks.
We recommend upgrading to the most recent 10.x release first, because most of what v11 removes is already deprecated there.
This checklist shows all migration steps for your selected platform. Some steps only apply to specific integrations or configuration options. For the full write-up of every change, see the migration guide.
TypeScript and other tooling won't catch all of these changes. Read through the steps below before upgrading, rather than upgrading and fixing what breaks.
Check prerequisites
4 leftRuntime, language and framework versions you need before upgrading.
Self-hosted Sentry 26.4.2 is the new minimum
Action requiredVersion 11 of the SDK requires Sentry self-hosted 26.4.2 or higher. Lower versions may continue to work, but are not supported. We recommend that you update self-hosted Sentry to the latest version.
Node.js 20.19.0 is the new minimum
Action requiredNode.js 18 is no longer supported. The minimum is 20.19.0, and Node.js 22 needs 22.12 or higher while Node.js 23 needs 23.2 or higher (>=20.19.0 <22.0.0 || >=22.12.0 <23.0.0 || >=23.2.0).
Move to a supported version everywhere the SDK is installed or your app is built: Dockerfiles, CI images, engines, .nvmrc, and serverless runtime settings.
The same supported Node.js range applies if you use Node.js to install dependencies or build a browser project. Loading the SDK directly in a browser from a CDN does not require Node.js.
TypeScript 5.0.4 is the new minimum
Action requiredThe minimum required TypeScript version is 5.0.4. The SDK no longer ships down-leveled types. Older TypeScript versions may continue to work, but no guarantees apply.
Fastify 3.21 is the new minimum
Action requiredFastify 3.0 through 3.20 are no longer supported. The minimum version is 3.21.
Update packages
5 leftInstalls, removals and moved entry points.
`@sentry/types` is no longer published
Action required@sentry/types is no longer published. Import all types from @sentry/core. The package has only re-exported from @sentry/core since v8.
Browser and server exports moved to `@sentry/core` subpaths
Action required@sentry/core exports only isomorphic code now. Browser-only exports live on @sentry/core/browser and server-only ones on @sentry/core/server, which keeps server code out of browser bundles. This only affects imports straight from @sentry/core, since the platform SDKs re-export as before. TypeScript reports it as has no exported member.
// Before
import { loadModule, trpcMiddleware } from "@sentry/core";
import type { BrowserClientReplayOptions } from "@sentry/core";
// After
import { loadModule, trpcMiddleware } from "@sentry/core/server";
import type { BrowserClientReplayOptions } from "@sentry/core/browser";
// Before
import { loadModule, trpcMiddleware } from "@sentry/core";
import type { BrowserClientReplayOptions } from "@sentry/core";
// After
import { loadModule, trpcMiddleware } from "@sentry/core/server";
import type { BrowserClientReplayOptions } from "@sentry/core/browser";
`@sentry/node-core` was merged back into `@sentry/node`
Action required@sentry/node-core was merged back into @sentry/node. With the reduced OpenTelemetry footprint, it no longer serves a purpose. Import everything from @sentry/node.
The webpack plugin requires webpack 5.1 and a new import path
Action requiredThe Sentry webpack plugin requires webpack 5.1 or newer. The @sentry/bundler-plugins/webpack5 entry point was removed. Update imports to @sentry/bundler-plugins/webpack:
// Before
import { sentryWebpackPlugin } from "@sentry/bundler-plugins/webpack5";
// After
import { sentryWebpackPlugin } from "@sentry/bundler-plugins/webpack";
// Before
import { sentryWebpackPlugin } from "@sentry/bundler-plugins/webpack5";
// After
import { sentryWebpackPlugin } from "@sentry/bundler-plugins/webpack";
The `/loader`, `/init`, and `/preload` entry points were removed
Action requiredThe init, preload, and loader entry points were removed from every server SDK, along with preloadOpenTelemetry(). Either --import your own instrument file, or --import the SDK and call Sentry.init() in code:
node --import ./instrument.mjs app.js
node --import @sentry/node/import app.js
node --import ./instrument.mjs app.js
node --import @sentry/node/import app.js
Make required code changes
31 leftOptions, APIs and config that changed and need your attention.
`sendDefaultPii` is replaced by `dataCollection`
Action requiredsendDefaultPii is replaced by dataCollection, which controls each category of collected data separately. Our blog post The Data Collection Control Panel covers the thinking behind it.
This is a behavior change, not a rename. In v10, an unset sendDefaultPii was restrictive. In v11, an unset dataCollection collects everything by default.
| Category | v10 default (sendDefaultPii off) | v11 default |
|---|---|---|
userInfo | false | true |
cookies | not collected | true |
httpHeaders | request + response, PII scrubbed | request + response |
httpBodies | not collected (size only) | all request/response |
urlQueryParams | true | true |
genAI | inputs + outputs not collected | inputs + outputs |
databaseQueryData | false | true |
stackFrameVariables | true | true |
frameContextLines | 7 | 5 |
If you set sendDefaultPii: true, remove it. The v11 default matches that behavior.
If you relied on the v10 default, set the baseline explicitly.
Sentry scrubs values whose key looks sensitive (e.g. auth, token, secret, password). The match runs on the key name, so treat it as best effort: a credential in a field that isn't named like one still reaches Sentry. Review your data scrubbing config for the categories v11 collects now, especially request and response bodies.
See the dataCollection option for the full list of categories.
`requestDataIntegration` overrides now interact with `dataCollection`
Behavior changeThe include options of requestDataIntegration stay an integration-level override. An explicit false keeps a category off the event, and an explicit true attaches it even when dataCollection has that category disabled. Any allow or deny filtering still applies, and a category that only include enables is filtered with the default denylist for sensitive values.
User IP address inference is now controlled by dataCollection.userInfo. To keep it for the data this integration collects, set requestDataIntegration({ include: { ip: true } }).
Span streaming is now the default
Behavior changeTracing moves to span streaming in v11. Instead of holding a trace in memory and sending one transaction when the root span ends, the SDK sends spans in small batches as they finish. Transactions no longer exist: what used to be one transaction event is a service span with its child spans.
That changes how spans are sent, named, and filtered. Most of it isn't caught by TypeScript, so check your filters, dashboards, and alerts.
Spans are no longer capped at 1000 per transaction, and individual payload limits are higher. See stream mode for how it works.
Because no transaction events are produced, beforeSendTransaction and ignoreTransactions no longer do anything, and beforeSendSpan receives a different payload.
Scope tags and extra no longer apply to spans
Action requiredStreamed spans only carry attributes, so scope tags and extra no longer reach any span, including the service span that replaced the transaction. They still apply to errors, so you don't have to remove them. In transaction mode (traceLifecycle: 'static') they keep landing on the transaction as before.
Set attributes for everything that should be searchable on spans, which also applies them to logs and metrics:
// Before: applied to the transaction
Sentry.setTag("order_id", order.id);
Sentry.setTags({ user_tier: user.tier });
// After: applied to spans, logs, and metrics
Sentry.setAttribute("order_id", order.id);
Sentry.setAttributes({ user_tier: user.tier });
// Before: applied to the transaction
Sentry.setTag("order_id", order.id);
Sentry.setTags({ user_tier: user.tier });
// After: applied to spans, logs, and metrics
Sentry.setAttribute("order_id", order.id);
Sentry.setAttributes({ user_tier: user.tier });
Attributes accept strings, numbers, booleans, and arrays of those, so numbers and booleans no longer have to be stringified. Like tags, they can be set on a specific scope:
// Applied to all spans, logs, and metrics of the application
Sentry.getGlobalScope().setAttributes({ "app.version": "2.1.0" });
// Applied to a single operation
Sentry.withScope((scope) => {
scope.setAttribute("checkout.step", "payment");
});
// Applied to all spans, logs, and metrics of the application
Sentry.getGlobalScope().setAttributes({ "app.version": "2.1.0" });
// Applied to a single operation
Sentry.withScope((scope) => {
scope.setAttribute("checkout.step", "payment");
});
`beforeSendSpan` receives the streamed span format
Action requiredbeforeSendSpan now runs as each span finishes and receives a StreamedSpanJSON object. Its fields were renamed:
Before (SpanJSON) | After (StreamedSpanJSON) |
|---|---|
description | name |
data | attributes |
op | attributes['sentry.op'] |
timestamp | end_timestamp |
status (string) | status ('ok' or 'error') |
// Before
Sentry.init({
beforeSendSpan: (span) => {
if (span.op === "db.query") {
span.description = scrub(span.description);
span.data["db.statement"] = scrub(span.data["db.statement"]);
}
return span;
},
});
// After
Sentry.init({
beforeSendSpan: (span) => {
if (span.attributes["sentry.op"] === "db.query") {
span.name = scrub(span.name);
span.attributes["db.query.text"] = scrub(
span.attributes["db.query.text"]
);
}
return span;
},
});
// Before
Sentry.init({
beforeSendSpan: (span) => {
if (span.op === "db.query") {
span.description = scrub(span.description);
span.data["db.statement"] = scrub(span.data["db.statement"]);
}
return span;
},
});
// After
Sentry.init({
beforeSendSpan: (span) => {
if (span.attributes["sentry.op"] === "db.query") {
span.name = scrub(span.name);
span.attributes["db.query.text"] = scrub(
span.attributes["db.query.text"]
);
}
return span;
},
});
The status field of that payload is always set, and holds only 'ok' or 'error'. The finer-grained statuses of v10 (internal_error, not_found, and the rest) all map to 'error', with the original value kept on the span's sentry.status.message attribute.
If you used withStreamedSpan(), remove the wrapper.
A callback that doesn't match your traceLifecycle is never invoked: an unwrapped one is ignored in transaction mode, a wrapped one in stream mode. In transaction mode, wrap it with Sentry.withStaticSpan() and it keeps receiving the old SpanJSON. Turn on debug logging to see a warning about the mismatch.
`beforeSendTransaction` no longer runs
Action requiredMove data changes to beforeSendSpan and guard on is_segment to target the service span, which is what used to be the transaction. Use ignoreSpans to drop spans: beforeSendSpan can only change spans, not drop them.
// Before
Sentry.init({
ignoreTransactions: ["GET /health"],
beforeSendTransaction: (event) => {
event.transaction = scrubIds(event.transaction);
return event;
},
});
// After
Sentry.init({
ignoreSpans: ["GET /health"],
beforeSendSpan: (span) => {
if (span.is_segment) {
span.name = scrubIds(span.name);
}
return span;
},
});
// Before
Sentry.init({
ignoreTransactions: ["GET /health"],
beforeSendTransaction: (event) => {
event.transaction = scrubIds(event.transaction);
return event;
},
});
// After
Sentry.init({
ignoreSpans: ["GET /health"],
beforeSendSpan: (span) => {
if (span.is_segment) {
span.name = scrubIds(span.name);
}
return span;
},
});
Scope tags and extra aren't carried over to streamed spans either.
`ignoreTransactions` is replaced by `ignoreSpans`
Action requiredignoreTransactions no longer does anything in stream mode because no transaction events are produced. Use ignoreSpans to drop spans.
Ignoring a service span drops its child spans with it, which is the same result as dropping a transaction. Because ignoreSpans applies to every span, narrow the filter with the object form so that child spans with the same name are kept:
Sentry.init({
ignoreSpans: [
{ name: "GET /health", attributes: { "sentry.op": "http.server" } },
],
});
Sentry.init({
ignoreSpans: [
{ name: "GET /health", attributes: { "sentry.op": "http.server" } },
],
});
`spanToJSON` returns the streamed span format
Action requiredSentry.spanToJSON() now returns a StreamedSpanJSON object, the same shape beforeSendSpan receives. The spanToStreamedSpanJSON helper was removed, so replace calls to it with spanToJSON.
Opting out of span streaming
FYISet traceLifecycle: 'static' to keep the previous model. In Node.js, Bun, Vercel Edge, and Cloudflare you can set the SENTRY_TRACE_LIFECYCLE=static environment variable instead.
Sentry.init({
traceLifecycle: "static",
// `beforeSendSpan` must be wrapped with `Sentry.withStaticSpan`
beforeSendSpan: Sentry.withStaticSpan((span) => {
span.description = scrub(span.description);
return span;
}),
});
Sentry.init({
traceLifecycle: "static",
// `beforeSendSpan` must be wrapped with `Sentry.withStaticSpan`
beforeSendSpan: Sentry.withStaticSpan((span) => {
span.description = scrub(span.description);
return span;
}),
});
In transaction mode, spanToStaticSpanJSON returns the static SpanJSON format.
Transaction mode only exists for backwards compatibility and will be removed in a future major version. Treat it as a temporary measure.
Span names are low cardinality
Behavior changeIn stream mode, span names follow the Sentry span name conventions. URLs, route parameters, and other client-supplied values are no longer part of the name:
| Span op | Before | After |
|---|---|---|
http.client | GET https://api.example.com/users/123 | GET api.example.com |
http.server | GET /users/123 | GET /users/:id, or GET |
pageload, navigation | /users/123 | /users/:id, or Pageload |
resource.* | /assets/app.js | cdn.example.com, or Resource |
graphql | query GetUser | GraphQL query |
queue.* | my-queue process, poll my-topic | process my-queue, receive my-topic |
db.query | SELECT * FROM "User" WHERE "id" = $1 | SELECT "User", or Database operation |
http.server names are unchanged when the SDK resolves a route, and fall back to the method alone when it can't. pageload and navigation fall back to Pageload and Navigation.
Database spans work the same way: a statement that touches no table (SELECT NOW()) summarizes to the bare operation (SELECT), and without a statement to summarize the name falls back to the database namespace, then to Database operation.
Whatever the name no longer carries stays on an attribute, in both trace lifecycles: url.full and url.domain, graphql.operation.name and the new graphql.processing.type, db.query.text, and so on.
ignoreSpans and tracesSampler both run when a span starts, so a span may not have its final name yet. Match on attributes instead:
Sentry.init({
// Before
ignoreSpans: ["/health", "SELECT * FROM health_check"],
tracesSampler: ({ name, inheritOrSampleWith }) =>
inheritOrSampleWith(name === "GET /health" ? 0 : 1),
// After
ignoreSpans: [
{ attributes: { "sentry.op": "pageload", "url.path": "/health" } },
{ attributes: { "db.query.text": "SELECT * FROM health_check" } },
],
tracesSampler: ({ attributes, inheritOrSampleWith }) =>
inheritOrSampleWith(attributes?.["url.path"] === "/health" ? 0 : 1),
});
Sentry.init({
// Before
ignoreSpans: ["/health", "SELECT * FROM health_check"],
tracesSampler: ({ name, inheritOrSampleWith }) =>
inheritOrSampleWith(name === "GET /health" ? 0 : 1),
// After
ignoreSpans: [
{ attributes: { "sentry.op": "pageload", "url.path": "/health" } },
{ attributes: { "db.query.text": "SELECT * FROM health_check" } },
],
tracesSampler: ({ attributes, inheritOrSampleWith }) =>
inheritOrSampleWith(attributes?.["url.path"] === "/health" ? 0 : 1),
});
The `enableLogs` option was removed
Action requiredThe enableLogs option was removed, including its _experiments variant. Logs are captured whenever you use their API (Sentry.logger.*) or add a logging integration such as consoleLoggingIntegration().
// Before
Sentry.init({
enableLogs: true,
});
// After
Sentry.init({});
// Before
Sentry.init({
enableLogs: true,
});
// After
Sentry.init({});
The `enableMetrics` option was removed
Action requiredThe enableMetrics option was removed, including its _experiments variant. Metrics are captured whenever you use their API (Sentry.metrics.*). The _experiments.beforeSendMetric callback moved to the top-level beforeSendMetric option.
// Before
Sentry.init({
_experiments: {
enableMetrics: true,
beforeSendMetric: (metric) => metric,
},
});
// After
Sentry.init({
beforeSendMetric: (metric) => metric,
});
// Before
Sentry.init({
_experiments: {
enableMetrics: true,
beforeSendMetric: (metric) => metric,
},
});
// After
Sentry.init({
beforeSendMetric: (metric) => metric,
});
Initializing via `--require` is no longer supported
Action requiredNode.js re-runs --require preloads on the internal module loader thread that the SDK spawns when it installs its instrumentation hooks, so Sentry.init() ran a second time on a thread that never executes your code. The SDK now skips initialization on that thread and warns when it was loaded through --require.
Use --import instead. It works for both ESM and CommonJS apps.
# Before
node --require ./instrument.js app.js
# After
node --import ./instrument.js app.js
# Before
node --require ./instrument.js app.js
# After
node --import ./instrument.js app.js
The SDK no longer sets up OpenTelemetry
Behavior changeSentry and OpenTelemetry are separate pipelines now, and you choose how they connect.
By default, the SDK no longer registers an OpenTelemetry tracer provider. It owns the full span lifecycle, produces native Sentry spans, and ignores spans created through @opentelemetry/api. You can now run your own OpenTelemetry setup next to Sentry without Sentry spans leaking into your pipeline, and without using Sentry components for export, context management, and trace propagation.
If you only use the Sentry SDK, tracing works as before and there's nothing to do.
To capture spans from @opentelemetry/api, see enableOpenTelemetrySetup. To run your own pipeline, see Running your own OpenTelemetry setup.
`skipOpenTelemetrySetup` is replaced by `enableOpenTelemetrySetup`
Action requiredskipOpenTelemetrySetup is replaced by enableOpenTelemetrySetup. Turn it on and the SDK registers a custom OpenTelemetry tracer provider, context manager, and propagator, which turns spans from @opentelemetry/api into Sentry spans. It's off by default, except on @sentry/nextjs and @sentry/sveltekit, which need it to capture the spans those frameworks emit.
Running your own OpenTelemetry setup
Action requiredKeep enableOpenTelemetrySetup off, turn Sentry tracing off, and add openTelemetryIntegration() to connect Sentry errors, logs, metrics, and crons to your OpenTelemetry traces. getOtlpTracesEndpoint() turns your DSN into the URL and auth headers of Sentry's OTLP endpoint.
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import * as Sentry from "@sentry/node";
const provider = new NodeTracerProvider({
spanProcessors: [
new BatchSpanProcessor(
new OTLPTraceExporter(Sentry.getOtlpTracesEndpoint("___PUBLIC_DSN___"))
),
],
});
provider.register();
Sentry.init({
dsn: "___PUBLIC_DSN___",
// No `tracesSampleRate`: OpenTelemetry owns spans, Sentry owns errors and logs
integrations: [Sentry.openTelemetryIntegration()],
});
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import * as Sentry from "@sentry/node";
const provider = new NodeTracerProvider({
spanProcessors: [
new BatchSpanProcessor(
new OTLPTraceExporter(Sentry.getOtlpTracesEndpoint("___PUBLIC_DSN___"))
),
],
});
provider.register();
Sentry.init({
dsn: "___PUBLIC_DSN___",
// No `tracesSampleRate`: OpenTelemetry owns spans, Sentry owns errors and logs
integrations: [Sentry.openTelemetryIntegration()],
});
On @sentry/nextjs and @sentry/sveltekit, set enableOpenTelemetrySetup: false explicitly.
The two pipelines stay separate: Sentry sends no spans, and no Sentry span reaches your OpenTelemetry pipeline.
This setup only works with Sentry tracing off, so leave tracesSampleRate unset. Sentry instruments many of the libraries OpenTelemetry does, so leaving tracing on gives you two spans for every operation, in two pipelines that never join up. With tracing off, Sentry's instrumentation stays installed and keeps isolating requests, but emits no spans. Note that this changed from v10, where skipOpenTelemetrySetup: true also turned off Sentry's HTTP and fetch spans.
If you used otlpIntegration() in v10, see the integration migration.
SentryContextManager, SentrySampler, and SentrySpanProcessor were removed, so there is no longer a way to route spans from your own provider into Sentry as Sentry spans. Export them over OTLP instead.
`otlpIntegration` was renamed to `openTelemetryIntegration`
Action requiredIf you used the v10 integration from @sentry/node-core/light/otlp: it moved to the main export of every server SDK, it no longer sets up an exporter (the setupOtlpTracesExporter and collectorUrl options were removed), and it was renamed to openTelemetryIntegration().
otlpIntegration() was renamed to openTelemetryIntegration(), because it sends nothing over OTLP. It reports itself as OpenTelemetry instead of OtlpIntegration. getOtlpTracesEndpoint() keeps its name.
For the exporter configuration, see Running your own OpenTelemetry setup.
`@sentry/opentelemetry` removals
Action requiredOpenTelemetry resources are no longer collected. contexts.otel.resource was dropped from events, and the SDK no longer reads OTEL_SERVICE_NAME and OTEL_RESOURCE_ATTRIBUTES.
getTraceContextForScope and getSentryResource were removed from @sentry/opentelemetry, along with the @opentelemetry/core peer dependency.
`@sentry/core` API removals
Action requiredThe following APIs were removed:
Scope.clear()was removed. To reset scope state, re-initialize the SDK or run your code in a fresh scope withwithScopeorwithIsolationScope.- The
disableInstrumentationWarningsoption and theMissingInstrumentationContexttype were removed. With channel-based instrumentation, the SDK can no longer detect that a framework was imported beforeSentry.init(). createSpanEnvelopeand theSpanEnvelopeandSpanItemtypes were removed. Standalone spans are gone: spans are sent on their transaction, or as streamed spans.- The positional
spanOriginargument ofinstrumentFetchRequestwas removed. Pass an options object as the last argument instead. - The internal
addAutoIpAddressToUserexport was removed.
The low-level propagateTrace option of getHttpClientSubscriptions and patchHttpModuleClient is called tracePropagation now, matching the httpIntegration option of the same name.
`@sentry/node` and server SDK API removals
Action requiredThe following APIs were removed from Node.js and server SDKs:
- The
registerEsmLoaderHooksoption was removed. The SDK no longer registersimport-in-the-middleESM loader hooks. generateInstrumentOnceandSentryContextManagerare no longer exported.- The deprecated
SentryHttpInstrumentationandSentryNodeFetchInstrumentationexports were removed. UseinstrumentHttpOutgoingRequests()andnativeNodeFetchIntegrationinstead. - The
connectinstrumentation and the deprecatedprismaInstrumentationoption were removed. Prisma works out of the box. - The
OpenTelemetryServerRuntimeOptionstype was removed.enableOpenTelemetrySetupis part of the SDK-specific options types, such asNodeOptions. - (AWS Lambda) The deprecated
disableAwsContextPropagationandstartTraceoptions and thetryPatchHandlerfunction were removed. To disable tracing, settracesSampleRateto0. - (Express) The deprecated
patchExpressModule(options)signature was removed. UsepatchExpressModule(moduleExports, getOptions)instead. - (Express)
ExpressIntegrationOptionsis no longer exported from@sentry/core. Import it from@sentry/node, which is the versionexpressIntegration()accepts. - (Fastify) The deprecated
instrumentFastify,handleFastifyError, andsetShouldHandleErrorexports were removed.
`httpIntegration` options were consolidated
Action requiredThe deprecated instrumentation.requestHook, instrumentation.responseHook, and instrumentation.applyCustomAttributesOnSpan hooks were removed, and several options were renamed. This only matters if you configured httpIntegration or httpServerSpansIntegration yourself.
Express errors are captured automatically
Action requiredExpress errors are captured by expressIntegration() now, so setupExpressErrorHandler(app) is no longer needed. It is deprecated and will be removed in the next major version.
Because the integration owns error capture, shouldHandleError moved to expressIntegration():
// Before
Sentry.init({ integrations: [Sentry.expressIntegration()] });
Sentry.setupExpressErrorHandler(app, {
shouldHandleError(error) {
return Number(error.statusCode ?? 500) >= 400;
},
});
// After
Sentry.init({
integrations: [
Sentry.expressIntegration({
shouldHandleError(error) {
return Number(error.statusCode ?? 500) >= 400;
},
}),
],
});
// Before
Sentry.init({ integrations: [Sentry.expressIntegration()] });
Sentry.setupExpressErrorHandler(app, {
shouldHandleError(error) {
return Number(error.statusCode ?? 500) >= 400;
},
});
// After
Sentry.init({
integrations: [
Sentry.expressIntegration({
shouldHandleError(error) {
return Number(error.statusCode ?? 500) >= 400;
},
}),
],
});
By default, Express captures 5xx errors and errors without a resolvable status, but not 3xx and 4xx errors. To capture errors yourself instead, set expressIntegration({ shouldHandleError: false }) and call Sentry.captureException in your own error-handling middleware.
setupExpressErrorHandler and expressErrorHandler moved from @sentry/core to @sentry/server-utils, along with patchExpressModule, which is deprecated for the same reason. Import them from your platform SDK, such as @sentry/node, as before.
Fastify errors are captured automatically
Action requiredFastify errors are captured by fastifyIntegration() now, so setupFastifyErrorHandler(app) is no longer needed. It is deprecated and will be removed in the next major version.
Because the integration owns error capture, shouldHandleError moved to fastifyIntegration().
The deprecated instrumentFastify, handleFastifyError, and setShouldHandleError exports were removed.
`honoIntegration` was removed
Action requiredhonoIntegration was removed. Use the @sentry/hono middleware instead.
`profilesSampleRate` and `profilesSampler` were removed
Action requiredThe legacy per-transaction profiling options were removed. Configure session-based profiling with profileSessionSampleRate and a profileLifecycle of 'trace' or 'manual' instead.
The `prune-profiler-binaries` script was removed
FYIThe prune-profiler-binaries script was removed from @sentry/profiling-node.
AI instrumentation moved out of `@sentry/core`
Action requiredThe following AI integration APIs changed:
- The
enableTruncationandstreamGenAiSpansflags were removed. Gen AI spans are always streamed and never truncated now. - The
addVercelAiProcessorshelper was removed. AddvercelAIIntegration()instead. - The AI instrumentation moved from
@sentry/coreto@sentry/server-utils. If you imported a helper such asinstrumentOpenAiClientorcreateLangChainCallbackHandlerdirectly from@sentry/core, import it from your platform SDK (for example@sentry/node) or from@sentry/server-utils.
Low-level AI exports are no longer public API
Action requiredLow-level provider instrumentation internals, integration-name constants, and their types are no longer exported from @sentry/core.
`InboundFilters` was renamed to `EventFilters`
Action requiredThe inboundFiltersIntegration export was removed, and the integration reports itself as EventFilters. Update references by name, for example in client.getIntegrationByName():
// Before
Sentry.init({
integrations: (integrations) =>
integrations.filter((integration) => integration.name !== "InboundFilters"),
});
// After
Sentry.init({
integrations: (integrations) =>
integrations.filter((integration) => integration.name !== "EventFilters"),
});
// Before
Sentry.init({
integrations: (integrations) =>
integrations.filter((integration) => integration.name !== "InboundFilters"),
});
// After
Sentry.init({
integrations: (integrations) =>
integrations.filter((integration) => integration.name !== "EventFilters"),
});
`instrumentLangGraph` was renamed to `instrumentStateGraph`
Action requiredinstrumentLangGraph was renamed to instrumentStateGraph, because it only instruments the StateGraph class.
`childProcessIntegration` was split in two
Action requiredchildProcessIntegration covers child_process, and the new workerThreadsIntegration covers worker_threads. Both are enabled by default, so no change is needed to keep the previous behavior.
The captureWorkerErrors option was removed, and worker thread errors are always captured as events. To opt out, remove the integration:
// Before
Sentry.init({
integrations: [
Sentry.childProcessIntegration({ captureWorkerErrors: false }),
],
});
// After
Sentry.init({
integrations: (integrations) =>
integrations.filter((integration) => integration.name !== "WorkerThreads"),
});
// Before
Sentry.init({
integrations: [
Sentry.childProcessIntegration({ captureWorkerErrors: false }),
],
});
// After
Sentry.init({
integrations: (integrations) =>
integrations.filter((integration) => integration.name !== "WorkerThreads"),
});
Note that captureWorkerErrors: false used to downgrade worker thread errors to a breadcrumb. That breadcrumb is gone, so removing the integration drops those errors entirely. The mechanism type also changed from auto.child_process.worker_thread to auto.node.worker_threads.
Verify behavior changes
8 leftCheck dashboards and alerts.
Channel-based instrumentation is the default
Behavior changeInstrumentation now runs through diagnostics channels (orchestrion) instead of import-in-the-middle. It allows instrumentation at run time and build time, which enables tracing on deployment targets like Vercel and Netlify, and on non-Node.js runtimes like Cloudflare, Bun, and Deno. Most setups need no changes.
`attachStacktrace` now defaults to `true`
Behavior changeSentry.captureMessage() events, and non-Error values passed to Sentry.captureException(), now attach a synthetic stack trace that points to the call site. Set attachStacktrace: false to restore the previous behavior.
Two consequences are worth checking after you upgrade:
- Issue grouping: Sentry groups events with and without stack traces differently, so you may see new issue groups.
- Release health: Events with a stack trace count as errors, so a
captureMessage()call marks the current session as errored. Crash-free session rate is not affected. For purely informational output, consider Sentry Logs instead.
`tracePropagationTargets` matching is now case-insensitive
Behavior changeString and regular expression matching for tracePropagationTargets no longer depends on casing. In browsers this was especially surprising, because the URL is normalized with new URL() before matching, which lower-cases the origin. A target such as 'myApi.com' could therefore never match a request to https://myApi.com.
Sentry.init({
// In a browser, neither of these matched `https://myApi.com` in v10. In v11 both do.
tracePropagationTargets: ["myApi.com", /^https:\/\/myApi\.com/],
});
Sentry.init({
// In a browser, neither of these matched `https://myApi.com` in v10. In v11 both do.
tracePropagationTargets: ["myApi.com", /^https:\/\/myApi\.com/],
});
If you relied on case-sensitive matching to tell two targets apart, narrow the target with a more specific path. The g and y flags are ignored now, because they made matching stateful and a target like /myApi\.com/g matched only every other request.
Span attributes were renamed to match semantic conventions
Behavior changeLegacy span attributes were replaced by their semantic-convention equivalents. Update any custom instrumentation, beforeSendSpan logic, dashboards, or alerts that reference them.
Span operations were consolidated
Behavior changeSpan ops are now a smaller, framework-neutral set. The detail that used to live in the op, such as the framework, library, method name, or lifecycle phase, is preserved in attributes like code.function.name, sentry.origin, db.system.name, db.operation.name, and faas.trigger.
Update anything that filters, groups, or alerts on span ops: dashboards, dynamic sampling rules, ignoreSpans, and beforeSendSpan. TypeScript doesn't catch these.
`vercelAIIntegration` is channel-based and no longer works on Vercel Edge
Behavior changevercelAIIntegration no longer works on Vercel Edge, which doesn't support diagnostics channels, and it no longer enhances the native OpenTelemetry spans the ai package emits. Those spans are captured as they are, so some agent monitoring capabilities are lost.
On Next.js, the vercelAIIntegration export stays available as a no-op on Edge builds.
AI integrations no longer trace non-inference operations
Behavior changeAI integrations now trace model invocations, tool calls, and agent invocations only. They no longer emit spans for Anthropic messages.countTokens, models.retrieve, or models.get, or LangGraph graph compilation with gen_ai.create_agent.
Update dashboards and alerts that reference these spans. LangGraph's gen_ai.invoke_agent and gen_ai.execute_tool spans are unchanged.
Unhandled rejections print less in `strict` mode
FYIIn strict mode, onUnhandledRejectionIntegration printed a warning in front of every unhandled rejection. It's now printed only when the rejection reason has no stack trace, which matches Node.js. Update log processing or tests that match on that text. The process still exits with code 1, and the reason is still written to stderr.
Optional cleanup
3 leftDeprecations and type tightening you can address later.
Type changes
FYISeveral public types changed:
- Several public types that used
anynow useunknown, includingStackFrame,SamplingContext,SentryError, andUser. You may need to narrow types explicitly. - Attribute typing and serialization were unified across the SDK.
- The
attributesfield of theSamplingContextpassed totracesSampleris required now. The SDK always provides it, so this only affects code that narrows or buildsSamplingContextobjects by hand. - The
attributesfield ofScopeDatais required now. This only affects code that constructsScopeDataobjects manually: addattributes: {}there. - The
endTimestampproperty was removed fromSentrySpanArguments. Callspan.end(timestamp)instead. BrowserOptionssupports theTransportOptionsgeneric now.
`withStreamedSpan()` is now a no-op
FYIIf you wrapped beforeSendSpan with withStreamedSpan() to opt into the streamed payload in v10, drop the wrapper. It's a no-op now that streamed payloads are the default, and it's deprecated.
`setupKoaErrorHandler` and `setupHapiErrorHandler` are deprecated
FYIKoa and Hapi errors are captured by their integrations now, so the error handler setup calls are no longer needed. They are deprecated and will be removed in the next major version.
setupKoaErrorHandler(app)setupHapiErrorHandler(server)
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").