Sentry SDK setupExpressErrorHandler isn't capturing bare exceptions on POST /flowsheet

[jakebromberg]

Problem

Investigation under BS#1271 surfaced two observability gaps that are independent of the root-cause controller fix:

Gap 1 — setupExpressErrorHandler didn't capture a bare TypeError

The POST /flowsheet burst captured under BS#1271 produced 8 spans with http.response.status_code: 500 and span.status: internal_error, but zero matching captured exceptions in the Sentry errors dataset. The errorHandler is wired correctly:

• apps/backend/app.ts:150 — Sentry.setupExpressErrorHandler(app, { shouldHandleError: shouldCaptureExpressError })
• apps/backend/app.ts:151 — app.use(errorHandler) (centralized handler that emits a 500 for non-WxycError)
• apps/backend/middleware/sentryErrorFilter.ts — shouldCaptureExpressError returns true for any non-LmlClientError with missing / NaN / ≥500 statusCode

A bare TypeError has no statusCode, so the filter resolves to true. The SDK should have captured. It didn't.

The "Mirror: create_entry failed" capture on POST /flowsheet (backend@v0.1.507, 2026-06-08) shows Sentry.captureException works in this transaction — so the gap is specific to setupExpressErrorHandler's express-middleware path, not Sentry's transport.

SDK: @sentry/node ^10.53.1.

Gap 2 — user.* attributes empty on http.server spans

All 8 failing http.server spans return empty for user.id, user.username, user.email, user.ip even though every failing request carried a JWT and went through requirePermissions. The user/ DJ attribution that would have let us identify the affected DJ's session is missing.

Why this matters

Together these gaps mean: when a 5xx code path doesn't have an explicit Sentry.captureException, the failure mode shows up as a span-only signal with no user attribution and no exception detail. Diagnosing BS#1271 required reading raw spans + correlating against existing tests; with the SDK working as documented, the bare TypeError would have surfaced as a typed Sentry issue immediately.

Next steps (suggested)

1. Reproduce setupExpressErrorHandler skipping a bare TypeError on Express 5 async-handler with @sentry/node ^10.53.1. The shouldHandleError option name may be silently deprecated in v10; check the SDK changelog / source.
2. If the SDK no longer honors shouldHandleError: either re-implement the LmlClientError filter as beforeSend, or stop relying on auto-capture and add explicit Sentry.captureException at controller boundaries that do 5xx.
3. Investigate why http.server spans don't carry user.* attributes. Probably needs an httpIntegration({ requestHook }) to read req.auth?.id and tag the span / scope.

Out of scope

• The BS#1271 controller fix (separate PR fix(flowsheet): guard not-found album lookup with 404 (closes BS#1271) #1366). That closes the immediate symptom by turning the case into a clean 404; this issue tracks the broader question of why the SDK didn't capture even though it was wired to.

[jakebromberg]

Verified the v10 shouldHandleError deprecation hypothesis (this issue body's "Next step 1") and ruled it out.

@sentry/core v10.53.1 source — @sentry/core/build/cjs/integrations/express/index.js:182-184:

const shouldHandleError = options?.shouldHandleError || utils.defaultShouldHandleError;
if (shouldHandleError(error)) { ... }

The shouldHandleError option IS still honored in v10.53.1. setupExpressErrorHandler(app, { shouldHandleError }) and expressErrorHandler({ shouldHandleError }) both receive ExpressHandlerOptions. The predicate gets called.

So the bare-TypeError-not-captured behavior has a different root cause.

Most likely culprit: the Express 5 async-handler boundary. If a controller throws inside async (req, res, next) => { ... } and the error path never reaches next(err) (or never reaches express's error pipeline at all), setupExpressErrorHandler has no opportunity to fire. Express 4 had the same gotcha; @sentry's older Sentry.Handlers.errorHandler patched it via requestHandler, but v10's setupExpressErrorHandler may have a narrower seam.

Suggested next investigation step: instrument apps/backend/middleware/sentryErrorFilter.ts shouldCaptureExpressError to log every invocation (count + status snapshot), reproduce the BS#1271 burst locally on Express 5 + @sentry/node ^10.53.1. If the predicate is never called, the error isn't reaching express's error pipeline at all — bug is upstream of the SDK.

Title reframe suggested: "v10 silently deprecated shouldHandleError" is misleading now. Better: "Express 5 async-handler errors bypass setupExpressErrorHandler pipeline" or similar.

---

Side note — Gap 2 (user.* empty on http.server spans): independent of Gap 1. Likely needs httpIntegration({ requestHook }) reading req.auth?.id and tagging the span / scope. Worth a sub-issue once Gap 1's root cause is nailed.

---

Audit complete on neighboring services: scanned the WXYC org for the same SDK idiom. Only one other legitimate fix surfaced — apps/auth/app.ts:363 had setupExpressErrorHandler without a predicate, defaulting to capture everything that looks 5xx-shaped. Fixed in #1388 (Closes #1387). No other Node services in the workspace use this SDK idiom.