Cannot apply global preRequest hooks: registration must occu

Error message

Cannot apply global preRequest hooks: registration must occur before initialization.

What it means

NestMicroservice.registerPreRequestHook logs this warning when a global preRequest hook (code meant to run before all enhancers for every pattern handler) is registered after initialization. The hook list is consumed when the microservice wires up its handlers during init(); a late registration only updates the ApplicationConfig, so the hook is never invoked for the already-built handlers. The call does not throw, so the hook silently does nothing.

Source

Thrown at packages/microservices/nest-microservice.ts:265

    guards = this.applyInstanceDecoratorIfRegistered<CanActivate>(...guards);
    this.applicationConfig.useGlobalGuards(...guards);
    guards.forEach(item =>
      this.graphInspector.insertOrphanedEnhancer({
        subtype: 'guard',
        ref: item,
      }),
    );
    return this;
  }

  /**
   * Registers a global preRequest hook (executed before all enhancers for every pattern handler).
   *
   * @param {...PreRequestHook} hooks
   */
  public registerPreRequestHook(...hooks: PreRequestHook[]): this {
    if (this.isInitialized) {
      this.logger.warn(
        'Cannot apply global preRequest hooks: registration must occur before initialization.',
      );
    }
    this.applicationConfig.registerPreRequestHook(...hooks);
    return this;
  }

  public async init(): Promise<this> {
    if (this.isInitialized) {
      return this;
    }

    // Lazy-load optional socket module (ESM-compatible)
    await this.loadSocketModule();
    await super.init();
    await this.registerModules();
    return this;
  }

View on GitHub (pinned to 3f8a0ce183)

Solutions

Call registerPreRequestHook() before `await app.listen()` / `await app.init()`.
If the hook needs async data, resolve it first and only then create + configure + listen, so registration stays pre-init.
Verify with a startup smoke request that the hook actually fired (e.g. assert the trace/tenant context appears), and fail CI on this warning.

Example fix

// before
const app = await NestFactory.createMicroservice(AppModule, opts);
await app.listen();
app.registerPreRequestHook(new TenantContextHook()); // warning: hook never runs

// after
const app = await NestFactory.createMicroservice(AppModule, opts);
app.registerPreRequestHook(new TenantContextHook());
await app.listen();

Defensive patterns

Strategy: validation

Validate before calling

const app = await NestFactory.createMicroservice(AppModule, opts);
if ((app as any).isInitialized) {
  throw new Error('Bootstrap order bug: pre-request hooks must be registered before init/listen');
}
app.registerPreRequestHook(new TenantContextHook());
await app.listen();

Prevention

Register pre-request hooks in the same bootstrap block as other global enhancers, before listen()
Resolve any async data the hook needs before app creation
Send a startup smoke request and assert the hook's side effect (trace id, tenant context) is present
Fail CI on this warning string in startup logs

When it happens

Trigger: Calling app.registerPreRequestHook(hook) after `await app.listen()` or `await app.init()`, typically for tenant-context, trace-propagation, or tenant/ledger setup hooks that are wired in from async bootstrap code or a plugin that activates once the broker connection is up.

Common situations: Multi-tenant context or correlation-id hooks installed after startup; plugins/SDKs (observability vendors) that attach hooks lazily on first request; hybrid apps where the microservice instance is configured after startAllMicroservices() has run.

Related errors

AI-assisted analysis of nestjs/nest@3f8a0ce183 (2026-08-21). Data as JSON: /api/errors/b072b980cc934b72. Report an issue: GitHub.