ref(node)!: Remove deprecated fastify exports, deprecate `setupFastifyErrorHandler` by mydea · Pull Request #23460 · getsentry/sentry-javascript

mydea · 2026-08-20T07:57:24Z

This consolidates the Fastify instrumentation onto a single, diagnostics-channel-based
fastifyIntegration and removes the deprecated/unneeded Fastify exports.

Node, Bun, and Elysia now use the channel-based fastifyIntegration from
@sentry/server-utils, and the old Node-specific integration (which wrapped the
OpenTelemetry Fastify instrumentation) is deleted. A single plugin now instruments
Fastify v3.21–v5, including error capture, so error handling no longer depends on
the Fastify version or on the user wiring anything up manually.

What changes for users

setupFastifyErrorHandler(app) is no longer required — errors are captured
automatically once fastifyIntegration() is added. It is now deprecated and kept
only as a thin shim that forwards a shouldHandleError callback to the integration.
shouldHandleError is configured directly on fastifyIntegration({ shouldHandleError })
for all supported versions. Previously this only applied to v5, with v3/v4 going through
setupFastifyErrorHandler.
Breaking: the deprecated instrumentFastify and handleFastifyError exports were
removed. They are no longer needed now that the integration instruments and captures on
its own.

Notable decisions

One channel-based plugin for all versions. Subscribing to Fastify's
fastify.initialization / error diagnostics channels lets us instrument v3.21 → v5
uniformly, without per-version branching and without asking users to register an error
handler by hand.
Per-request error dedupe. On v5 the same route-handler error surfaces on both the
diagnostics channel and the onError hook. Rather than leaning on captureException's
error-object dedupe, we mark the request with a non-enumerable symbol once captured and
bail out on the second path. Errors that reach only one path (thrown in an onRequest
hook, or on v3/v4 which have no channel) are still captured exactly once.

Root cause note (instance patching)

The plugin is applied synchronously from the fastify.initialization channel rather
than via instance.register(). register() defers work to the boot phase (listen()/
ready()), but addHook runs immediately — so hooks a user adds synchronously before
listen() would otherwise slip through un-instrumented. Patching synchronously (the init
channel fires before Fastify() returns) ensures every hook is wrapped. The onError
hook is registered as an async hook so Fastify awaits it correctly and the error response
is not left hanging.

Tests

Dropped the separate app-handle-error-override.ts E2E apps and their
playwright.override.config.mjs from the node-fastify-3/4/5 test apps.
Moved override coverage into node-integration-tests (scenario-error-handler.mjs),
and added a no-tracing scenario plus a regression case for a hook added synchronously
before listen().

Migration guide updated for both the setupFastifyErrorHandler deprecation and the
removed exports.

github-actions · 2026-08-20T08:04:43Z

size-limit report 📦

Path	Size	% Change	Change
@sentry/browser	28.57 kB	-	-
@sentry/browser - with treeshaking flags	26.92 kB	-	-
@sentry/browser - with treeshaking flags tracing without tracing	26.82 kB	-	-
@sentry/browser (incl. Tracing)	48.61 kB	-	-
@sentry/browser (incl. Tracing + Span Streaming)	48.63 kB	-	-
@sentry/browser (incl. Tracing, Profiling)	51.54 kB	-	-
@sentry/browser (incl. Tracing, Replay)	88.1 kB	-	-
@sentry/browser (incl. Tracing, Replay) - with treeshaking flags	77.48 kB	-	-
@sentry/browser (incl. Tracing, Replay with Canvas)	92.8 kB	-	-
@sentry/browser (incl. Tracing, Replay, Feedback)	105.48 kB	-	-
@sentry/browser (incl. Feedback)	45.79 kB	-	-
@sentry/browser (incl. sendFeedback)	33.35 kB	-	-
@sentry/browser (incl. FeedbackAsync)	38.46 kB	-	-
@sentry/browser (incl. Metrics)	29.51 kB	-	-
@sentry/browser (incl. Logs)	29.8 kB	-	-
@sentry/browser (incl. Metrics & Logs)	30.43 kB	-	-
@sentry/react	30.31 kB	-	-
@sentry/react (incl. Tracing)	50.82 kB	-	-
@sentry/vue	35.69 kB	-	-
@sentry/vue (incl. Tracing)	50.86 kB	-	-
@sentry/svelte	28.59 kB	-	-
CDN Bundle	30.36 kB	-	-
CDN Bundle (incl. Tracing)	49.09 kB	-	-
CDN Bundle (incl. Logs, Metrics)	32.56 kB	-	-
CDN Bundle (incl. Tracing, Logs, Metrics)	50.98 kB	-	-
CDN Bundle (incl. Replay, Logs, Metrics)	73 kB	-	-
CDN Bundle (incl. Tracing, Replay)	86.6 kB	-	-
CDN Bundle (incl. Tracing, Replay, Logs, Metrics)	88.5 kB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback)	92.38 kB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback, Logs, Metrics)	94.3 kB	-	-
CDN Bundle - uncompressed	89.97 kB	-	-
CDN Bundle (incl. Tracing) - uncompressed	146.77 kB	-	-
CDN Bundle (incl. Logs, Metrics) - uncompressed	96.26 kB	-	-
CDN Bundle (incl. Tracing, Logs, Metrics) - uncompressed	152.46 kB	-	-
CDN Bundle (incl. Replay, Logs, Metrics) - uncompressed	225.42 kB	-	-
CDN Bundle (incl. Tracing, Replay) - uncompressed	266.27 kB	-	-
CDN Bundle (incl. Tracing, Replay, Logs, Metrics) - uncompressed	271.94 kB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback) - uncompressed	279.96 kB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback, Logs, Metrics) - uncompressed	285.62 kB	-	-
@sentry/nextjs (client)	53.39 kB	-	-
@sentry/sveltekit (client)	49.05 kB	-	-
@sentry/core/server	65.3 kB	-	-
@sentry/core/browser	52.35 kB	-	-
@sentry/node	122.35 kB	-0.3%	-363 B 🔽
@sentry/node/import (ESM hook with diagnostics-channel injection)	85.22 kB	-	-
@sentry/node - without tracing	87.67 kB	-0.36%	-312 B 🔽
@sentry/node - without channel injection	102.05 kB	-0.34%	-340 B 🔽
@sentry/aws-serverless	95.82 kB	-0.38%	-365 B 🔽
@sentry/cloudflare (withSentry) - minified	199.57 kB	-	-
@sentry/cloudflare (withSentry)	495.71 kB	-	-

View base workflow run

isaacs

Found a few nits and questions/cleanup opportunities, mostly fairly low severity.

This is a really nice cleanup, very deep cuts. Love to see it!

The only blocking issue imo is that Fastify will silently not track errors anymore unless tracing is enabled, and requiring someone to specifically opt into the integration isn't meaningfully easier than requiring them to attach a custom error handler. I'd recommend just having it turned on all the time.

Also, there's some orphaned e2e test files that I think can be deleted:

dev-packages/e2e-tests/test-applications/node-fastify-3/playwright.override.config.mjs
dev-packages/e2e-tests/test-applications/node-fastify-4/playwright.override.config.mjs
dev-packages/e2e-tests/test-applications/node-fastify-5/playwright.override.config.mjs

mydea · 2026-08-24T07:23:06Z

@isaacs I will go through your feedback in more details later, but I think the core thing should be handled here: #23473 - which is true, we need to ensure to always run this, even without performance, for this to make sense!

s1gr1d · 2026-08-24T09:22:46Z

Just quickly cross-referencing this other Fastify PR here:

ref!(node): Remove Fastify error handler setter #23411

isaacs · 2026-08-24T14:38:38Z

@mydea

I think the core thing should be handled here: #23473

Ah! Yes, that does evaporate a lot of the comments here. Seems fine to dismiss that stuff then, and leave it for the next PR to address.

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit d6cde9e. Configure here.}

isaacs

All concerns addressed! LGTM! 🚢

…yErrorHandler`

Resolves conflicts with #23460, which consolidated Fastify onto a single channel-based `fastifyIntegration` and moved everything out of `packages/node/src/integrations/tracing/fastify/`. Conflict resolutions (all modify/delete — upstream deletion accepted): - The three e2e `app-handle-error-override.ts` apps: #23460 deleted them and moved override coverage into node-integration-tests. - `packages/node/src/integrations/tracing/fastify/index.ts`: deleted, the integration now lives in `@sentry/server-utils`. - `docs/migration/v11-end-state.md`: deleted by #23623, which folded the guide into MIGRATION.md. The Fastify entries were ported there. Reapplied on top: `setupFastifyErrorHandler` no longer accepts `shouldHandleError`. After removing `setShouldHandleError`, forwarding the option was the shim's only remaining job, so it is now a deprecated no-op kept purely so existing `setupFastifyErrorHandler(app)` calls do not break. The node-integration-test that covered the option was repointed at `fastifyIntegration({ shouldHandleError })`. Co-Authored-By: Opus 5 <noreply@anthropic.com>

…ndler` and `setupFasitfyErrorHandler` (#23734) Express: - #23732 - #23464 - #23763 Fastify: - #23460 - #23464 - #23411

cursorBot reviewed Aug 20, 2026
View reviewed changes

Comment threaddev-packages/e2e-tests/test-applications/node-fastify-3/package.json
Comment threadpackages/server-utils/src/integrations/fastify/instrumentation.ts Outdated

cursorBot reviewed Aug 20, 2026
View reviewed changes

Comment threaddev-packages/node-integration-tests/suites/tracing/fastify/test.ts

mydea marked this pull request as ready for review August 20, 2026 10:53

mydea requested review from a team as code owners August 20, 2026 10:53

mydea requested review from JPeer264, chargome, isaacs and s1gr1d and removed request for a teamAugust 20, 2026 10:53

sentryBot reviewed Aug 20, 2026
View reviewed changes

Comment threadpackages/server-utils/src/integrations/fastify/errors.ts Outdated

mydea marked this pull request as draft August 20, 2026 11:33

mydea force-pushed the fn/streamline-fastify branch from 3004b8c to 3a04de5Compare August 20, 2026 13:37

mydea marked this pull request as ready for review August 20, 2026 13:55

sentryBot reviewed Aug 20, 2026
View reviewed changes

Comment threadpackages/server-utils/src/integrations/fastify/instrumentation.ts Outdated

mydea force-pushed the fn/streamline-fastify branch from 3a04de5 to 07fbd58Compare August 21, 2026 09:50

isaacs requested changes Aug 23, 2026
View reviewed changes

s1gr1d mentioned this pull request Aug 24, 2026
ref!(node): Remove Fastify error handler setter #23411
Merged

mydea force-pushed the fn/streamline-fastify branch from 129ac3e to ffd446aCompare August 24, 2026 12:26

cursorBot reviewed Aug 24, 2026
View reviewed changes

Comment threadpackages/server-utils/src/integrations/fastify/instrumentation.ts Outdated
Comment threaddev-packages/e2e-tests/test-applications/node-fastify-3/tests/transactions.test.ts

mydea force-pushed the fn/streamline-fastify branch from ffd446a to 3024abcCompare August 24, 2026 12:51

sentryBot reviewed Aug 24, 2026
View reviewed changes

Comment threadpackages/server-utils/src/integrations/fastify/instrumentation.ts Outdated

mydea force-pushed the fn/streamline-fastify branch from 3024abc to 88fc5d8Compare August 26, 2026 07:18

mydea requested a review from isaacs August 26, 2026 07:18

cursorBot reviewed Aug 26, 2026
View reviewed changes

Comment threaddev-packages/e2e-tests/test-applications/nestjs-fastify/tests/transactions.test.ts Outdated

isaacs approved these changes Aug 26, 2026
View reviewed changes

mydea added 22 commits August 27, 2026 08:47

ref(node)!: Remove deprecated fastify exports, deprecate `setupFastif…
3b1ca9b
…yErrorHandler`

fixes and stuff
62afe44

skip perf instrumentation without spans
0a54203

handle no-tracing scenario
219d7f7

combine into single plugin
7829c28

revert span only test
c6fab7f

fix tests
9b46481

migration entry
b8157b6

avoid dedupe, rely on base error dedupe
59baa87

delete straggling files
791b03b

ref collapse into single handler
26dcc91

dedupe errors through request
9ebd356

fix order and stuff
cf9e33b

avoid unnecessary stuff
aca32ce

fixes and cleanup and stuff
658a452

cleanup
9ceccd0

fix test
da277f3

fix var shadowing
1bec423

fix nestjs fastify
10157ee

add regression test
f8f0a4f

fix tests
2d508b6

fix test
95e8de1

mydea force-pushed the fn/streamline-fastify branch from d6cde9e to 95e8de1Compare August 27, 2026 06:57

mydea merged commit 2325c8d into developAug 27, 2026
204 checks passed

mydea deleted the fn/streamline-fastify branch August 27, 2026 07:13

s1gr1d mentioned this pull request Aug 28, 2026
feat(v10/node): Deprecate shouldHandleError on setupExpressErrorHandler and setupFasitfyErrorHandler#23734
Merged

s1gr1d added a commit that referenced this pull request Aug 31, 2026
feat(v10/node): Deprecate shouldHandleError on `setupExpressErrorHa…
bea4d38
…ndler` and `setupFasitfyErrorHandler` (#23734) Express: - #23732 - #23464 - #23763 Fastify: - #23460 - #23464 - #23411

Uh oh!

Uh oh!

Conversation

mydea commented Aug 20, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changes for users

Notable decisions

Root cause note (instance patching)

Tests

Uh oh!

Uh oh!

Uh oh!

github-actionsBot commented Aug 20, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

size-limit report 📦

Uh oh!

Uh oh!

Uh oh!

Uh oh!

isaacs left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mydea commented Aug 24, 2026

Uh oh!

s1gr1d commented Aug 24, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

isaacs commented Aug 24, 2026

Uh oh!

cursorBot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

isaacs left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

mydea commented Aug 20, 2026•
edited
Loading

github-actionsBot commented Aug 20, 2026•
edited
Loading