{"record":{"id":"fa6c59cd1922a18e","repo":"nestjs/nest","slug":"calling-the-methodname-in-the-preview-mode-is","errorCode":null,"errorMessage":"Calling the \"${methodName}\" in the preview mode is not supported.","messagePattern":"Calling the \"(.+?)\" in the preview mode is not supported\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/nest-application-context.ts","lineNumber":483,"sourceCode":"  /**\n   * Calls the `beforeApplicationShutdown` function on the registered\n   * modules and children.\n   */\n  protected async callBeforeShutdownHook(signal?: string): Promise<void> {\n    const modulesSortedByDistance = [\n      ...this.getModulesToTriggerHooksOn(),\n    ].reverse();\n\n    for (const module of modulesSortedByDistance) {\n      await callBeforeAppShutdownHook(module, signal);\n    }\n  }\n\n  protected assertNotInPreviewMode(methodName: string) {\n    if (this.appOptions.preview) {\n      const error = `Calling the \"${methodName}\" in the preview mode is not supported.`;\n      this.logger.error(error);\n      throw new Error(error);\n    }\n  }\n\n  private getModulesToTriggerHooksOn(): Module[] {\n    if (this._moduleRefsForHooksByDistance) {\n      return this._moduleRefsForHooksByDistance;\n    }\n    const modulesContainer = this.container.getModules();\n    const compareFn = (a: Module, b: Module) => b.distance - a.distance;\n    const modulesSortedByDistance = Array.from(modulesContainer.values()).sort(\n      compareFn,\n    );\n\n    this._moduleRefsForHooksByDistance = this.appOptions?.preview\n      ? modulesSortedByDistance.filter(moduleRef => moduleRef.initOnPreview)\n      : modulesSortedByDistance;\n    return this._moduleRefsForHooksByDistance;\n  }","sourceCodeStart":465,"sourceCodeEnd":501,"githubUrl":"https://github.com/nestjs/nest/blob/dd75d7bd8c5e88048587e6768d36eb695f3e7a25/packages/core/nest-application-context.ts#L465-L501","documentation":"With `NestFactory.create(AppModule, { preview: true })` NestJS builds the whole DI graph and route table but never starts a server — it exists for compile-time analysis (e.g., CI checks of module wiring and route registration). Runtime-only entry points are guarded by assertNotInPreviewMode: calling `listen()`, `startAllMicroservices()`, `close()` (or other guarded lifecycle methods) in preview mode throws immediately with 'Calling the \"X\" in the preview mode is not supported.'.","triggerScenarios":"A single bootstrap file used both for `nest build --preview`-style checks and real serving: the `preview: true` option is left enabled (or toggled by env var) while the code still unconditionally calls `app.listen(port)` or `app.startAllMicroservices()`; CI pipelines flipping a PREVIEW env var without gating listen().","commonSituations":"Migrating CI to validate modules without binding ports; monorepos sharing one main.ts across deploy targets; env-driven config where NEST_PREVIEW stays 'true' in a deployed image by mistake.","solutions":["Gate the runtime calls: only call `listen()`/`startAllMicroservices()` when preview is disabled.","Derive `preview` from one explicit env variable and reuse the same variable for the gate.","Split entrypoints: main.ts for serving, a separate preview.ts for compile-time checks.","Verify the flag in the deployed environment (NEST_PREVIEW / APP_PREVIEW) is not stuck at true."],"exampleFix":"// before\nconst app = await NestFactory.create(AppModule, { preview: isPreview });\nawait app.listen(3000); // throws when isPreview\n\n// after\nconst app = await NestFactory.create(AppModule, { preview: isPreview });\nif (!isPreview) {\n  await app.listen(3000);\n}","handlingStrategy":"validation","validationCode":"// Single source of truth for the mode; gate every runtime call on it\nconst isPreview = process.env.NEST_PREVIEW === 'true';\nconst app = await NestFactory.create(AppModule, { preview: isPreview });\n\nif (!isPreview) {\n  await app.listen(process.env.PORT ?? 3000);\n  await app.startAllMicroservices(); // also guarded\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Derive `preview` from one env variable and reuse that variable for every listen()/close() gate.","Keep a dedicated preview entrypoint (preview.ts) so serving code can never run in preview builds.","In pipelines, assert NEST_PREVIEW is unset in deploy images before shipping."],"tags":["preview-mode","bootstrap","lifecycle","configuration"],"backgroundTag":"preview-mode-runtime-call","analyzedSha":"dd75d7bd8c5e88048587e6768d36eb695f3e7a25","analyzedAt":"2026-08-21T19:39:39.867Z","contentChangedAt":"2026-08-21T19:39:39.867Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}