fix(server-utils): Skip Fastify 4xx errors raised before the reply status is set

Fastify runs `onError` hooks before it applies the error's status to the reply,
so for errors like an unparseable request body `reply.statusCode` is still the
default 200 in `defaultShouldHandleError`, and they were captured. Resolve the
status the same way Fastify does when the reply has not been set yet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: tobias-schnabel

dev-packages/node-integration-tests/suites/tracing/fastify/scenario.mjs

@@ -26,6 +26,10 @@ app.get('/test-exception/:id', async request => {
   throw new Error(`This is an exception with id ${request.params.id}`);
 });
 
+app.post('/test-body', async () => {
+  return {};
+});
+
 app.get('/test-inbound-headers/:id', async request => {
   return { headers: request.headers, id: request.params.id };
 });

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

@@ -182,5 +182,29 @@ describe('fastify v5 auto-instrumentation', () => {
       runner.makeRequest('get', '/test-exception/456', { expectError: true });
       await runner.completed();
     });
+
+    test('does not capture 4xx errors raised before the reply status is set', async () => {
+      const runner = createRunner()
+        .expect({
+          event: {
+            exception: {
+              values: [
+                {
+                  type: 'Error',
+                  value: 'This is an exception with id 789',
+                },
+              ],
+            },
+          },
+        })
+        .start();
+      // Fastify rejects an empty JSON body with a 400 and runs `onError` hooks before setting that status.
+      await runner.makeRequest('post', '/test-body', {
+        headers: { 'content-type': 'application/json' },
+        expectError: true,
+      });
+      await runner.makeRequest('get', '/test-exception/789', { expectError: true });
+      await runner.completed();
+    });
   });
 });

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

@@ -7,8 +7,23 @@ export const INTEGRATION_NAME = 'Fastify' as const;
  *
  * 3xx and 4xx errors are not sent by default.
  */
-export function defaultShouldHandleError(_error: Error, _request: FastifyRequest, reply: FastifyReply): boolean {
-  const statusCode = reply.statusCode;
+export function defaultShouldHandleError(error: Error, _request: FastifyRequest, reply: FastifyReply): boolean {
+  const statusCode = getReplyStatusCode(error, reply);
   // 3xx and 4xx errors are not sent by default.
   return statusCode >= 500 || statusCode <= 299;
 }
+
+/**
+ * Fastify runs `onError` hooks before it applies the error's status to the reply
+ * (e.g. for a request body that fails to parse), so `reply.statusCode` can still be
+ * the default 200. In that case, resolve the status the same way Fastify will.
+ */
+function getReplyStatusCode(error: Error, reply: FastifyReply): number {
+  if (reply.statusCode !== 200) {
+    return reply.statusCode;
+  }
+
+  const { statusCode, status } = error as { statusCode?: unknown; status?: unknown };
+  const errorStatusCode = Number(statusCode || status);
+  return errorStatusCode >= 400 ? errorStatusCode : 500;
+}

packages/server-utils/test/integrations/fastify/utils.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest';
+import type { FastifyReply, FastifyRequest } from '../../../src/integrations/fastify/types';
+import { defaultShouldHandleError } from '../../../src/integrations/fastify/utils';
+
+const request: FastifyRequest = { method: 'POST', routeOptions: { url: '/' } };
+
+function reply(statusCode: number): FastifyReply {
+  return { statusCode } as FastifyReply;
+}
+
+function errorWith(props: { statusCode?: number; status?: number }): Error {
+  return Object.assign(new Error('test error'), props);
+}
+
+describe('defaultShouldHandleError', () => {
+  // Fastify runs `onError` hooks before it applies the error's status to the reply,
+  // e.g. for a body that fails to parse, so `reply.statusCode` is still the default 200 there.
+  describe('when the reply status has not been set yet', () => {
+    it('skips errors carrying a 4xx `statusCode`', () => {
+      expect(defaultShouldHandleError(errorWith({ statusCode: 400 }), request, reply(200))).toBe(false);
+    });
+
+    it('skips errors carrying a 4xx `status`', () => {
+      expect(defaultShouldHandleError(errorWith({ status: 404 }), request, reply(200))).toBe(false);
+    });
+
+    it('skips errors carrying a 4xx status as a string', () => {
+      expect(
+        defaultShouldHandleError(Object.assign(new Error('test error'), { statusCode: '404' }), request, reply(200)),
+      ).toBe(false);
+    });
+
+    it('captures errors carrying a 5xx status', () => {
+      expect(defaultShouldHandleError(errorWith({ statusCode: 503 }), request, reply(200))).toBe(true);
+    });
+
+    it('captures errors without a status', () => {
+      expect(defaultShouldHandleError(new Error('test error'), request, reply(200))).toBe(true);
+    });
+
+    it('captures errors carrying a status below 400, which Fastify sends as a 500', () => {
+      expect(defaultShouldHandleError(errorWith({ statusCode: 302 }), request, reply(200))).toBe(true);
+    });
+  });
+
+  describe('when the reply status has been set', () => {
+    it('skips errors on a 4xx reply', () => {
+      expect(defaultShouldHandleError(new Error('test error'), request, reply(404))).toBe(false);
+    });
+
+    it('skips errors on a 3xx reply', () => {
+      expect(defaultShouldHandleError(new Error('test error'), request, reply(302))).toBe(false);
+    });
+
+    it('captures errors on a 5xx reply', () => {
+      expect(defaultShouldHandleError(errorWith({ statusCode: 400 }), request, reply(500))).toBe(true);
+    });
+  });
+});