feat(hono): Add shouldHandleError as middleware option (#21205)

s1gr1d · web-flow · commit 556bcb391de9 · 2026-05-28T12:29:00.000Z
Adds the error filtering logic to the Hono `sentry()` middleware. It already exists in the to-be deprecated `honoIntegration`: #17743 `isExpectedError` was renamed to `defaultShouldHandleError` so the name is matching with the user-provided parameter. I also removed the special catching **within** the middleware, as it's just "duplicated code". The error bubbles through the Hono context anyway - it's a bit simpler now. Closes #21204
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -14,6 +14,23 @@
   [Sentry TanStack Start SDK docs](https://docs.sentry.io/platforms/javascript/guides/tanstackstart-react/). Please reach out on
   [GitHub](https://github.com/getsentry/sentry-javascript/issues/new/choose) if you have any feedback or concerns.
 
+- **feat(hono): Add `shouldHandleError` option to `sentry()` middleware**
+
+  The `sentry()` middleware now accepts a `shouldHandleError` callback to control which errors are captured and sent to Sentry. By default, 3xx/4xx HTTP errors are ignored and 5xx errors and plain `Error` objects are captured. Return `true` from the callback to capture an error, `false` to suppress it.
+
+  ```ts
+  app.use(
+    sentry(app, {
+      dsn: '__DSN__',
+      shouldHandleError(error) {
+        const status = (error as { status?: number })?.status;
+        // Capture 401/403 in addition to the default 5xx errors
+        return status === 401 || status === 403 || typeof status !== 'number' || status >= 500;
+      },
+    }),
+  );
+  ```
+
 - **test(tanstackstart-react): Move initialization to client entry point ([#21161](https://github.com/getsentry/sentry-javascript/pull/21161))**
 
   Change the recommended setup for the SDK to do `Sentry.init()` in the client entry file to capture telemetry that is emitted ahead of page hydration.
diff --git a/dev-packages/e2e-tests/test-applications/hono-4/tests/errors.test.ts b/dev-packages/e2e-tests/test-applications/hono-4/tests/errors.test.ts
@@ -146,7 +146,7 @@ test.describe('middleware errors', () => {
 
     const errorEvent = await errorPromise;
     expect(errorEvent.exception?.values?.[0]?.value).toBe('Service Unavailable from middleware');
-    expect(errorEvent.exception?.values?.[0]?.mechanism?.type).toBe('auto.middleware.hono');
+    expect(errorEvent.exception?.values?.[0]?.mechanism?.type).toBe('auto.http.hono.context_error');
     expect(errorEvent.exception?.values?.[0]?.mechanism?.handled).toBe(false);
     expect(errorEvent.transaction).toBe('GET /test-errors/middleware-http-exception');
 
diff --git a/dev-packages/e2e-tests/test-applications/hono-4/tests/middleware.test.ts b/dev-packages/e2e-tests/test-applications/hono-4/tests/middleware.test.ts
@@ -113,7 +113,7 @@ for (const { name, prefix } of SCENARIOS) {
       expect(errorEvent.exception?.values?.[0]?.mechanism).toEqual(
         expect.objectContaining({
           handled: false,
-          type: 'auto.middleware.hono',
+          type: 'auto.http.hono.context_error',
         }),
       );
 
diff --git a/packages/hono/README.md b/packages/hono/README.md
@@ -188,3 +188,24 @@ app.use(
 
 serve(app);
 ```
+
+## Filtering errors
+
+By default, `@sentry/hono` captures 5xx errors and plain `Error` objects, and ignores 3xx/4xx HTTP errors (redirects, not-found, bad request, etc.).
+
+Use `shouldHandleError` to override this on a per-error basis:
+
+```ts
+app.use(
+  sentry(app, {
+    dsn: '__DSN__',
+    shouldHandleError(error) {
+      const status = (error as { status?: number })?.status;
+      // Capture 401/403 in addition to the default 5xx errors
+      return status === 401 || status === 403 || typeof status !== 'number' || status >= 500;
+    },
+  }),
+);
+```
+
+Return `true` to capture the error, `false` to suppress it.
diff --git a/packages/hono/src/bun/middleware.ts b/packages/hono/src/bun/middleware.ts
@@ -3,16 +3,15 @@ import { init } from './sdk';
 import type { Env, Hono, MiddlewareHandler } from 'hono';
 import { requestHandler, responseHandler } from '../shared/middlewareHandlers';
 import { applyPatches } from '../shared/applyPatches';
+import type { SentryHonoMiddlewareOptions } from '../shared/types';
 
-export interface HonoBunOptions extends Options<BaseTransportOptions> {}
+export interface HonoBunOptions extends Options<BaseTransportOptions>, SentryHonoMiddlewareOptions {}
 
 /**
  * Sentry middleware for Hono running in a Bun runtime environment.
  */
 export const sentry = <E extends Env>(app: Hono<E>, options: HonoBunOptions): MiddlewareHandler => {
-  const isDebug = options.debug;
-
-  isDebug && debug.log('Initialized Sentry Hono middleware (Bun)');
+  options.debug && debug.log('Initialized Sentry Hono middleware (Bun)');
 
   init(options);
 
@@ -23,6 +22,6 @@ export const sentry = <E extends Env>(app: Hono<E>, options: HonoBunOptions): Mi
 
     await next(); // Handler runs in between Request above ⤴ and Response below ⤵
 
-    responseHandler(context);
+    responseHandler(context, options.shouldHandleError);
   };
 };
diff --git a/packages/hono/src/cloudflare/middleware.ts b/packages/hono/src/cloudflare/middleware.ts
@@ -4,8 +4,9 @@ import type { Env, Hono, MiddlewareHandler } from 'hono';
 import { buildFilteredIntegrations } from '../shared/buildFilteredIntegrations';
 import { requestHandler, responseHandler } from '../shared/middlewareHandlers';
 import { applyPatches } from '../shared/applyPatches';
+import type { SentryHonoMiddlewareOptions } from '../shared/types';
 
-export interface HonoCloudflareOptions extends Options<BaseTransportOptions> {}
+export interface HonoCloudflareOptions extends Options<BaseTransportOptions>, SentryHonoMiddlewareOptions {}
 
 /**
  * Sentry middleware for Hono on Cloudflare Workers.
@@ -36,10 +37,15 @@ export function sentry<E extends Env>(
   applyPatches(app);
 
   return async (context, next) => {
+    const shouldHandleError =
+      typeof options === 'function'
+        ? options(context.env as E['Bindings']).shouldHandleError
+        : options.shouldHandleError;
+
     requestHandler(context);
 
     await next(); // Handler runs in between Request above ⤴ and Response below ⤵
 
-    responseHandler(context);
+    responseHandler(context, shouldHandleError);
   };
 }
diff --git a/packages/hono/src/node/middleware.ts b/packages/hono/src/node/middleware.ts
@@ -2,6 +2,7 @@ import { type BaseTransportOptions, debug, type Options, getClient } from '@sent
 import type { Env, Hono, MiddlewareHandler } from 'hono';
 import { requestHandler, responseHandler } from '../shared/middlewareHandlers';
 import { applyPatches } from '../shared/applyPatches';
+import type { SentryHonoMiddlewareOptions } from '../shared/types';
 
 export interface HonoNodeOptions extends Options<BaseTransportOptions> {}
 
@@ -13,7 +14,7 @@ export interface HonoNodeOptions extends Options<BaseTransportOptions> {}
  *
  * **Note:** You must initialize Sentry separately before using this middleware. Typically, this is done by calling `Sentry.init()` in an `instrument.ts` file and loading it via the Node `--import` flag.
  */
-export const sentry = <E extends Env>(app: Hono<E>): MiddlewareHandler => {
+export const sentry = <E extends Env>(app: Hono<E>, options?: SentryHonoMiddlewareOptions): MiddlewareHandler => {
   const sentryClient = getClient();
   if (sentryClient === undefined) {
     debug.warn(
@@ -31,6 +32,6 @@ export const sentry = <E extends Env>(app: Hono<E>): MiddlewareHandler => {
 
     await next(); // Handler runs in between Request above ⤴ and Response below ⤵
 
-    responseHandler(context);
+    responseHandler(context, options?.shouldHandleError);
   };
 };
diff --git a/packages/hono/src/shared/defaultShouldHandleError.ts b/packages/hono/src/shared/defaultShouldHandleError.ts
@@ -0,0 +1,19 @@
+/**
+ * Default implementation of the `shouldHandleError` callback.
+ *
+ * Returns `true` (capture) for 5xx errors and any error without a `status` property
+ *
+ * Returns `false` (skip) for 3xx and 4xx errors (they still generate spans and transactions for tracing)
+ *
+ * Checks any error-like value that carries a numeric `status` property. This covers
+ * Hono's `HTTPException`, third-party middleware errors, and custom error subclasses.
+ */
+export function defaultShouldHandleError(error: unknown): boolean {
+  if (typeof error !== 'object' || error === null) {
+    return true;
+  }
+
+  const status = (error as { status?: unknown }).status;
+
+  return !(typeof status === 'number' && status >= 300 && status < 500);
+}
diff --git a/packages/hono/src/shared/isExpectedError.ts b/packages/hono/src/shared/isExpectedError.ts
diff --git a/packages/hono/src/shared/middlewareHandlers.ts b/packages/hono/src/shared/middlewareHandlers.ts
@@ -12,7 +12,8 @@ import {
 import type { Context } from 'hono';
 import { routePath } from 'hono/route';
 import { hasFetchEvent } from '../utils/hono-context';
-import { isExpectedError } from './isExpectedError';
+import { defaultShouldHandleError } from './defaultShouldHandleError';
+import { type SentryHonoMiddlewareOptions } from '../shared/types';
 
 /**
  * Request handler for Hono framework
@@ -33,11 +34,16 @@ export function requestHandler(context: Context): void {
 /**
  * Response handler for Hono framework
  */
-export function responseHandler(context: Context): void {
-  if (context.error && !isExpectedError(context.error)) {
-    getClient()?.captureException(context.error, {
-      mechanism: { handled: false, type: 'auto.http.hono.context_error' },
-    });
+export function responseHandler(
+  context: Context,
+  shouldHandleError?: SentryHonoMiddlewareOptions['shouldHandleError'],
+): void {
+  if (context.error) {
+    if ((shouldHandleError ?? defaultShouldHandleError)(context.error)) {
+      getClient()?.captureException(context.error, {
+        mechanism: { handled: false, type: 'auto.http.hono.context_error' },
+      });
+    }
   }
 }
 
diff --git a/packages/hono/src/shared/types.ts b/packages/hono/src/shared/types.ts
@@ -0,0 +1,24 @@
+/**
+ * Middleware-specific options shared across all Hono runtime adapters.
+ * These options are distinct from the SDK initialization options (DSN, sample rates, etc.).
+ */
+export interface SentryHonoMiddlewareOptions {
+  /**
+   * Determines whether a given Hono error thrown in the response should be captured and sent to Sentry.
+   *
+   * When not provided, the default behavior applies: 3xx and 4xx HTTP errors are
+   * considered expected and are not captured. All other errors are captured.
+   *
+   * @example
+   * // Capture everything, including 4xx errors:
+   * shouldHandleError: () => true
+   *
+   * @example
+   * // Capture only 5xx errors and suppress everything else:
+   * shouldHandleError: (err) => {
+   *   const status = (err as { status?: number })?.status;
+   *   return typeof status === 'number' ? status >= 500 : true;
+   * }
+   */
+  shouldHandleError?: (error: unknown) => boolean;
+}
diff --git a/packages/hono/src/shared/wrapMiddlewareSpan.ts b/packages/hono/src/shared/wrapMiddlewareSpan.ts
@@ -1,5 +1,4 @@
 import {
-  captureException,
   getActiveSpan,
   getOriginalFunction,
   getRootSpan,
@@ -10,7 +9,7 @@ import {
   type WrappedFunction,
 } from '@sentry/core';
 import { type MiddlewareHandler } from 'hono';
-import { isExpectedError } from './isExpectedError';
+import { defaultShouldHandleError } from './defaultShouldHandleError';
 
 const MIDDLEWARE_ORIGIN = 'auto.middleware.hono';
 
@@ -44,13 +43,11 @@ export function wrapMiddlewareWithSpan(handler: MiddlewareHandler): MiddlewareHa
       try {
         return await handler(context, next);
       } catch (error) {
-        if (!isExpectedError(error)) {
+        // Error capture is handled by `responseHandler` via `context.error`, so this wrapper only sets
+        // span status (based on our default "error" conditions) and rethrows (no `captureException`).
+        if (defaultShouldHandleError(error)) {
           span.setStatus({ code: SPAN_STATUS_ERROR, message: 'internal_error' });
-          captureException(error, {
-            mechanism: { handled: false, type: MIDDLEWARE_ORIGIN },
-          });
         }
-
         throw error;
       } finally {
         span.end();
diff --git a/packages/hono/test/shared/defaultShouldHandleError.test.ts b/packages/hono/test/shared/defaultShouldHandleError.test.ts
@@ -0,0 +1,78 @@
+import { HTTPException } from 'hono/http-exception';
+import { describe, expect, it } from 'vitest';
+import { defaultShouldHandleError } from '../../src/shared/defaultShouldHandleError';
+
+describe('defaultShouldHandleError', () => {
+  describe('HTTPException', () => {
+    it('returns false for 4xx HTTPException (skip)', () => {
+      expect(defaultShouldHandleError(new HTTPException(400, { message: 'Bad Request' }))).toBe(false);
+      expect(defaultShouldHandleError(new HTTPException(401, { message: 'Unauthorized' }))).toBe(false);
+      expect(defaultShouldHandleError(new HTTPException(403, { message: 'Forbidden' }))).toBe(false);
+      expect(defaultShouldHandleError(new HTTPException(404, { message: 'Not Found' }))).toBe(false);
+      expect(defaultShouldHandleError(new HTTPException(422, { message: 'Unprocessable Entity' }))).toBe(false);
+      expect(defaultShouldHandleError(new HTTPException(499))).toBe(false);
+    });
+
+    it('returns true for 5xx HTTPException (capture)', () => {
+      expect(defaultShouldHandleError(new HTTPException(500, { message: 'Internal Server Error' }))).toBe(true);
+      expect(defaultShouldHandleError(new HTTPException(502, { message: 'Bad Gateway' }))).toBe(true);
+      expect(defaultShouldHandleError(new HTTPException(503, { message: 'Service Unavailable' }))).toBe(true);
+    });
+  });
+
+  describe('custom error classes with status property', () => {
+    it('returns false for custom Error subclass with 4xx status (skip)', () => {
+      class AuthError extends Error {
+        status = 401;
+      }
+      expect(defaultShouldHandleError(new AuthError('unauthorized'))).toBe(false);
+    });
+
+    it('returns true for custom Error subclass with 5xx status (capture)', () => {
+      class DbError extends Error {
+        status = 500;
+      }
+      expect(defaultShouldHandleError(new DbError('connection lost'))).toBe(true);
+    });
+
+    it('returns false for plain object with 4xx status (skip)', () => {
+      expect(defaultShouldHandleError({ status: 404, message: 'Not Found' })).toBe(false);
+      expect(defaultShouldHandleError({ status: 400 })).toBe(false);
+    });
+
+    it('returns true for plain object with 5xx status (capture)', () => {
+      expect(defaultShouldHandleError({ status: 500, message: 'Internal Server Error' })).toBe(true);
+    });
+  });
+
+  describe('non-HTTP errors', () => {
+    it('returns true for plain Error without status (capture)', () => {
+      expect(defaultShouldHandleError(new Error('something broke'))).toBe(true);
+    });
+
+    it('returns true for non-object values (capture)', () => {
+      expect(defaultShouldHandleError('string error')).toBe(true);
+      expect(defaultShouldHandleError(42)).toBe(true);
+      expect(defaultShouldHandleError(null)).toBe(true);
+      expect(defaultShouldHandleError(undefined)).toBe(true);
+      expect(defaultShouldHandleError(true)).toBe(true);
+    });
+
+    it('returns true when status is not a number (capture)', () => {
+      expect(defaultShouldHandleError({ status: '404' })).toBe(true);
+      expect(defaultShouldHandleError({ status: null })).toBe(true);
+      expect(defaultShouldHandleError({ status: undefined })).toBe(true);
+    });
+
+    it('returns false for 3xx status (skip)', () => {
+      expect(defaultShouldHandleError({ status: 301 })).toBe(false);
+      expect(defaultShouldHandleError({ status: 302 })).toBe(false);
+      expect(defaultShouldHandleError({ status: 399 })).toBe(false);
+    });
+
+    it('returns true for 2xx status (capture)', () => {
+      expect(defaultShouldHandleError({ status: 200 })).toBe(true);
+      expect(defaultShouldHandleError({ status: 299 })).toBe(true);
+    });
+  });
+});
diff --git a/packages/hono/test/shared/isExpectedError.test.ts b/packages/hono/test/shared/isExpectedError.test.ts
diff --git a/packages/hono/test/shared/middlewareHandlers.test.ts b/packages/hono/test/shared/middlewareHandlers.test.ts
diff --git a/packages/hono/test/shared/patchAppUse.test.ts b/packages/hono/test/shared/patchAppUse.test.ts
diff --git a/packages/hono/test/shared/wrapMiddlewareSpan.test.ts b/packages/hono/test/shared/wrapMiddlewareSpan.test.ts
