{"record":{"id":"cd0c2d54a6b848a9","repo":"vercel/next.js","slug":"an-error-occurred-while-loading-the-instrumentatio","errorCode":null,"errorMessage":"An error occurred while loading the instrumentation hook","messagePattern":"An error occurred while loading the instrumentation hook","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/next/src/server/next-server.ts","lineNumber":366,"sourceCode":"      }\n    }\n  }\n\n  protected async handleUpgrade(): Promise<void> {\n    // The web server does not support web sockets, it's only used for HMR in\n    // development.\n  }\n\n  protected async loadInstrumentationModule() {\n    if (!this.serverOptions.dev) {\n      try {\n        this.instrumentation = await getInstrumentationModule(\n          this.dir,\n          this.nextConfig.distDir\n        )\n      } catch (err: any) {\n        if (err.code !== 'MODULE_NOT_FOUND') {\n          throw new Error(\n            'An error occurred while loading the instrumentation hook',\n            { cause: err }\n          )\n        }\n      }\n    }\n    return this.instrumentation\n  }\n\n  protected async prepareImpl() {\n    await super.prepareImpl()\n    await this.runInstrumentationHookIfAvailable()\n  }\n\n  protected async runInstrumentationHookIfAvailable() {\n    await ensureInstrumentationRegistered(this.dir, this.nextConfig.distDir)\n  }\n","sourceCodeStart":348,"sourceCodeEnd":384,"githubUrl":"https://github.com/vercel/next.js/blob/0ae8c72462952df163f1b1e0726641bc5b40dc93/packages/next/src/server/next-server.ts#L348-L384","documentation":"Thrown by NextNodeServer.loadInstrumentationModule() in production (non-dev) mode when loading the instrumentation module (instrumentation.ts/js) fails with any error OTHER than MODULE_NOT_FOUND. The instrumentation hook runs custom code at server startup for OpenTelemetry/Sentry/etc., so a runtime error in that user-authored module propagates as this wrapped error with the original as the cause.","triggerScenarios":"Running `next start` (production, not dev) where instrumentation.{ts,js} exists but throws during module evaluation — e.g. a bad import path, a top-level throw, referencing an undefined env var that breaks an imported SDK, or a syntax error. The code calls getInstrumentationModule(dir, distDir) and only swallows err.code === 'MODULE_NOT_FOUND'; every other error is re-thrown wrapped in this message.","commonSituations":"An observability SDK (Sentry, OpenTelemetry) is initialized in instrumentation.ts with a missing API key env var that causes the SDK init to throw; importing a Node-only module into an edge instrumentation file; a refactor left a broken import; the distDir build of instrumentation is stale after editing the source.","solutions":["Inspect the `cause` of the thrown Error — it holds the original stack from your instrumentation module; fix the offending line in instrumentation.ts.","Run `next build` again to ensure the instrumentation module is recompiled into distDir, then `next start`.","Temporarily test the instrumentation file in isolation (`node --import ./instrumentation.js` or a unit test) to reproduce the load failure outside Next.","Verify all env vars and external packages required by instrumentation.ts are available in the production environment."],"exampleFix":"// before (instrumentation.ts)\nexport async function register() {\n  Sentry.init({ dsn: process.env.SENTRY_DSN.toUpperCase() }) // throws if SENTRY_DSN undefined\n}\n// after\nexport async function register() {\n  if (process.env.SENTRY_DSN) {\n    Sentry.init({ dsn: process.env.SENTRY_DSN })\n  }\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"// In your server bootstrap, guard the Next server start so an instrumentation\n// failure surfaces a clear message instead of crashing silently.\ntry {\n  await app.prepare()\n} catch (err) {\n  if (/loading the instrumentation hook/i.test(err.message)) {\n    console.error('instrumentation.ts failed to load:', err.cause)\n  }\n  throw err\n}","preventionTips":["Keep instrumentation.ts minimal and dependency-light; test it in isolation.","Never reference undefined env vars in top-level instrumentation code; guard them.","Run `next build` and a smoke `next start` in CI to catch instrumentation load errors before deploy.","Ensure all packages imported in instrumentation.ts are installed in the production environment."],"tags":["instrumentation","production","startup","server"],"analyzedSha":"0ae8c72462952df163f1b1e0726641bc5b40dc93","analyzedAt":"2026-08-06T19:44:29.143Z","schemaVersion":2},"datasetVersion":"2026-08-07T02:17:10.218Z"}