feat(node): Auto-register Hapi error handler on server start

MIGRATION.md

@@ -293,6 +293,12 @@ Affected SDKs: `@sentry/node` and all dependents that re-export it (e.g. `@sentr
 
 The Koa error handler is now registered automatically when your app starts, so you no longer need to call `setupKoaErrorHandler`. The function is deprecated and will be removed in a future major version; you should no longer call it.
 
+### `setupHapiErrorHandler` is deprecated (Hapi errors are captured automatically)
+
+Affected SDKs: `@sentry/node` and all dependents that re-export it (e.g. `@sentry/aws-serverless`, `@sentry/google-cloud-serverless`, `@sentry/astro`, `@sentry/remix`, `@sentry/solidstart`, `@sentry/sveltekit`, `@sentry/bun`, `@sentry/elysia`).
+
+The Hapi error handler is now registered automatically when your server starts, so you no longer need to call `setupHapiErrorHandler` yourself. The function is deprecated and will be removed in a future major version; you should no longer call it.
+
 ### Initializing via `--require` is no longer supported
 
 Affected SDKs: `@sentry/node` and all dependents.

dev-packages/e2e-tests/test-applications/node-hapi/src/app.js

@@ -118,7 +118,6 @@ const init = async () => {
 
 (async () => {
   init();
-  await Sentry.setupHapiErrorHandler(server);
   await server.start();
   console.log('Server running on %s', server.info.uri);
 })();

dev-packages/node-integration-tests/suites/tracing/hapi/instrument-should-handle-error.mjs

@@ -0,0 +1,17 @@
+import * as Sentry from '@sentry/node';
+import { loggingTransport } from '@sentry-internal/node-integration-tests';
+
+Sentry.init({
+  traceLifecycle: 'static',
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  release: '1.0',
+  tracesSampleRate: 1.0,
+  transport: loggingTransport,
+  integrations: [
+    // Drop the "Dropped error" — the default predicate would capture it (it's a 5xx). This custom
+    // predicate must win over the default one installed by the earlier `setupHapiErrorHandler` call.
+    Sentry.hapiIntegration({
+      shouldHandleError: error => error?.message !== 'Dropped error',
+    }),
+  ],
+});

dev-packages/node-integration-tests/suites/tracing/hapi/scenario-should-handle-error.mjs

@@ -0,0 +1,33 @@
+import Hapi from '@hapi/hapi';
+import * as Sentry from '@sentry/node';
+import { sendPortToRunner } from '@sentry-internal/node-integration-tests';
+
+const run = async () => {
+  const server = Hapi.server({
+    host: 'localhost',
+    port: 0,
+  });
+
+  server.route({
+    method: 'GET',
+    path: '/dropped',
+    handler: () => new Error('Dropped error'),
+  });
+
+  server.route({
+    method: 'GET',
+    path: '/captured',
+    handler: () => new Error('Captured error'),
+  });
+
+  // Runs BEFORE `server.start()` and installs the default predicate. The integration's
+  // auto-registration (with the custom predicate) only fires at `server.start()`, so the custom
+  // predicate must still take precedence over this earlier default-valued attach.
+  await Sentry.setupHapiErrorHandler(server);
+
+  await server.start();
+
+  sendPortToRunner(server.info.port);
+};
+
+run();

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

@@ -1,6 +1,5 @@
 import Boom from '@hapi/boom';
 import Hapi from '@hapi/hapi';
-import * as Sentry from '@sentry/node';
 import { sendPortToRunner } from '@sentry-internal/node-integration-tests';
 
 const port = 5999;
@@ -67,7 +66,6 @@ const run = async () => {
   // Server extension produces a `middleware` span.
   server.ext('onPreResponse', (request, h) => h.continue);
 
-  await Sentry.setupHapiErrorHandler(server);
   await server.start();
 
   sendPortToRunner(port);

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

@@ -135,4 +135,37 @@ describe('hapi auto-instrumentation', () => {
       await runner.completed();
     });
   });
+
+  // Regression test: a `setupHapiErrorHandler` call before `server.start()` installs the default
+  // predicate. The integration's own auto-registration (with a custom `shouldHandleError`) fires later,
+  // at `server.start()`, and must still win. The custom predicate drops "Dropped error" (which the
+  // default would capture), so only the "Captured error" sentinel should come through — if the default
+  // predicate were active, "Dropped error" would be captured first and fail this assertion.
+  createEsmAndCjsTests(
+    __dirname,
+    'scenario-should-handle-error.mjs',
+    'instrument-should-handle-error.mjs',
+    (createRunner, test) => {
+      test('integration `shouldHandleError` overrides an earlier default-valued `setupHapiErrorHandler`', async () => {
+        const runner = createRunner()
+          .ignore('transaction')
+          .expect({
+            event: {
+              exception: {
+                values: [
+                  {
+                    type: 'Error',
+                    value: 'Captured error',
+                  },
+                ],
+              },
+            },
+          })
+          .start();
+        await runner.makeRequest('get', '/dropped', { expectError: true });
+        await runner.makeRequest('get', '/captured', { expectError: true });
+        await runner.completed();
+      });
+    },
+  );
 });

packages/astro/src/index.server.ts

@@ -125,6 +125,7 @@ export {
   setAttribute,
   setAttributes,
   setupExpressErrorHandler,
+  // oxlint-disable-next-line typescript/no-deprecated
   setupHapiErrorHandler,
   // oxlint-disable-next-line typescript/no-deprecated
   setupKoaErrorHandler,

packages/aws-serverless/src/index.ts

@@ -123,6 +123,7 @@ export {
   workerThreadsIntegration,
   createSentryWinstonTransport,
   hapiIntegration,
+  // oxlint-disable-next-line typescript/no-deprecated
   setupHapiErrorHandler,
   spotlightIntegration,
   initOpenTelemetry,

packages/bun/src/index.ts

@@ -140,6 +140,7 @@ export {
   getOtlpTracesEndpoint,
   processSessionIntegration,
   hapiIntegration,
+  // oxlint-disable-next-line typescript/no-deprecated
   setupHapiErrorHandler,
   spotlightIntegration,
   initOpenTelemetry,

packages/elysia/src/index.ts

@@ -117,6 +117,7 @@ export {
   prismaIntegration,
   processSessionIntegration,
   hapiIntegration,
+  // oxlint-disable-next-line typescript/no-deprecated
   setupHapiErrorHandler,
   spotlightIntegration,
   initOpenTelemetry,

packages/google-cloud-serverless/src/index.ts

@@ -120,6 +120,7 @@ export {
   getOtlpTracesEndpoint,
   processSessionIntegration,
   hapiIntegration,
+  // oxlint-disable-next-line typescript/no-deprecated
   setupHapiErrorHandler,
   spotlightIntegration,
   initOpenTelemetry,

packages/node/src/index.ts

@@ -42,6 +42,7 @@ export {
   instrumentStateGraph,
   instrumentStateGraphCompile,
 } from '@sentry/server-utils';
+// oxlint-disable-next-line typescript/no-deprecated
 export { setupHapiErrorHandler } from './integrations/tracing/hapi';
 // oxlint-disable-next-line typescript/no-deprecated -- deprecated but still re-exported for backwards compatibility
 export { setupKoaErrorHandler } from './integrations/tracing/koa';

packages/node/src/integrations/tracing/hapi.ts

@@ -0,0 +1,17 @@
+import { attachHapiErrorHandler } from '@sentry/server-utils';
+
+/**
+ * Add a Hapi plugin to capture errors to Sentry.
+ *
+ * @deprecated The error handler is now registered automatically when the Hapi
+ * server starts (via the orchestrion `@hapi/hapi` instrumentation), so calling
+ * this is no longer necessary. It remains a safe, idempotent operation when the
+ * handler is already attached, and is kept for setups where auto-registration is
+ * unavailable. This will be removed in a future major version.
+ *
+ * @param server The Hapi server to attach the error handler to
+ */
+export async function setupHapiErrorHandler(server: unknown): Promise<void> {
+  // oxlint-disable-next-line typescript/no-deprecated
+  attachHapiErrorHandler(server as Parameters<typeof attachHapiErrorHandler>[0]);
+}