Cannot apply global interceptors: registration must occur be

Error message

Cannot apply global interceptors: registration must occur before initialization.

What it means

NestMicroservice.useGlobalInterceptors logs this warning when called after init()/listen() has completed. Interceptor chains for every pattern handler are assembled during initialization, so interceptors registered later are captured in the ApplicationConfig and shown in the internal graph as orphaned enhancers, but they never wrap the existing handlers. The call returns `this` and does not throw — the interceptors are just inert.

Source

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

    );
    this.applicationConfig.useGlobalPipes(...pipes);
    pipes.forEach(item =>
      this.graphInspector.insertOrphanedEnhancer({
        subtype: 'pipe',
        ref: item,
      }),
    );
    return this;
  }

  /**
   * Registers global interceptors (will be used for every pattern handler).
   *
   * @param {...NestInterceptor} interceptors
   */
  public useGlobalInterceptors(...interceptors: NestInterceptor[]): this {
    if (this.isInitialized) {
      this.logger.warn(
        'Cannot apply global interceptors: registration must occur before initialization.',
      );
    }

    interceptors = this.applyInstanceDecoratorIfRegistered<NestInterceptor>(
      ...interceptors,
    );
    this.applicationConfig.useGlobalInterceptors(...interceptors);
    interceptors.forEach(item =>
      this.graphInspector.insertOrphanedEnhancer({
        subtype: 'interceptor',
        ref: item,
      }),
    );
    return this;
  }

  public useGlobalGuards(...guards: CanActivate[]): this {

View on GitHub (pinned to 3f8a0ce183)

Solutions

Register all global interceptors before `await app.listen()` / `await app.init()`.
If registration timing is uncertain, use @UseInterceptors() on individual pattern handlers instead.
Initialize tracing/APM SDKs before creating the microservice so their interceptors can be passed in bootstrap order.
Treat this warning as a CI failure — it means the interceptor will not run in production.

Example fix

// before
const app = await NestFactory.createMicroservice(AppModule, opts);
await app.listen();
app.useGlobalInterceptors(new TracingInterceptor()); // warning: never applied

// after
const app = await NestFactory.createMicroservice(AppModule, opts);
app.useGlobalInterceptors(new TracingInterceptor());
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: register interceptors before init/listen');
}
app.useGlobalInterceptors(new LoggingInterceptor());
await app.listen();

Prevention

Initialize tracing/APM SDKs before creating the microservice so interceptors can be registered pre-init
Keep a single bootstrap function with a fixed order: create -> register enhancers -> listen
Smoke-test that the interceptor actually fires (assert log/trace output) after startup
Fail CI on this warning string in startup logs

When it happens

Trigger: Calling app.useGlobalInterceptors(new LoggingInterceptor()) after `await app.listen()` or `await app.init()` on a NestFactory.createMicroservice instance, or configuring the NestMicroservice returned by connectMicroservice() after startAllMicroservices() has initialized it.

Common situations: Logging/tracing/metrics interceptors wired up from async bootstrap code (APM agents, OpenTelemetry) that initializes after the service is already serving; interceptors registered in onApplicationBootstrap of a lazily loaded module; hybrid apps where the microservice part is configured later than the HTTP part.

Related errors

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