The request pipeline: middleware, guards, interceptors, pipes, filters

The seven stages, in order

Before you write the first line of a guard or interceptor, you need to know where in the pipeline it runs — because the stage determines what data is available, and putting logic at the wrong stage is exactly how the hook’s three-week security hole happened.

Every HTTP request that reaches a Nest handler runs a fixed gauntlet of enhancers. The order is not configurable, and getting it wrong in your head is how authorization logic ends up in the wrong place. Left to right:

middleware → guard → interceptor (pre) → pipe → handler → interceptor (post) → filter (on throw)

1. Middleware runs first, at the Express/Fastify level, bound in a module’s configure(consumer). It has raw req, res, next — but it runs before Nest has resolved which handler will serve the route, so it has no ExecutionContext, no handler reference, no route metadata.
2. Guards run next. canActivate(ctx) returns a boolean (or a Promise/Observable of one); false short-circuits with a 403. This is where authorization lives. A guard does get an ExecutionContext, so it can read handler metadata via Reflector — but the request body has not been validated or transformed yet.
3. Interceptors (pre half) wrap the handler. Code before next.handle() runs here.
4. Pipes run on the handler arguments — @Body(), @Param(), @Query() — validating and transforming them (ValidationPipe, ParseIntPipe). They run after guards and after the interceptor’s pre-half, right before the handler.
5. The route handler executes.
6. Interceptors (post half) — the RxJS pipe after next.handle() (map, timeout, caching, response shaping) runs on the way out. One interceptor therefore gives you two execution points around the handler.
7. Exception filters catch anything thrown in any of the above, mapping the error to an HTTP response. A filter is the last line.

// A guard runs at stage 2 — BEFORE pipes. It sees handler metadata, not a validated DTO.
@Injectable()
export class RolesGuard implements CanActivate {
  constructor(
    private readonly reflector: Reflector,    // injected — reads @Roles() metadata
    private readonly users: UsersService,     // injected — checks roles in the DB
  ) {}

  async canActivate(ctx: ExecutionContext): Promise<boolean> {
    const required = this.reflector.get<string[]>('roles', ctx.getHandler());
    if (!required) return true;                // no @Roles() → public
    const { user } = ctx.switchToHttp().getRequest();
    return this.users.hasAnyRole(user.id, required);
  }
}

// An interceptor is two execution points: before next.handle() and after, via RxJS.
@Injectable()
export class TimingInterceptor implements NestInterceptor {
  intercept(ctx: ExecutionContext, next: CallHandler): Observable<unknown> {
    const start = Date.now();                  // PRE-handler half
    return next.handle().pipe(                 // ← handler runs here
      map((data) => ({ data, ms: Date.now() - start })), // POST-handler half
    );
  }
}

Binding scope: where an enhancer applies

Each of the four enhancer kinds (guards, interceptors, pipes, filters) binds at one of four scopes: global, controller (a class-level @UseGuards()), method (@UseGuards() on the handler), and for pipes also parameter (@Body(new ValidationPipe())). Within a kind, execution runs global → controller → method, outermost first. Scope answers “where does this apply”; it does not change the stage ordering above.

The DI trap: new versus APP_GUARD

Here is the trap that bit the RolesGuard. There are two ways to register a global enhancer, and they are not equivalent:

// ANTI-PATTERN: you `new` it yourself, so it lives OUTSIDE the DI container.
// It cannot inject Reflector or UsersService — you'd have to hand-build them.
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalGuards(new RolesGuard(/* what do I pass here? */));
  await app.listen(3000);
}

// CORRECT: register via the APP_GUARD token in a module. Nest instantiates it
// through DI, so Reflector and UsersService are injected normally.
@Module({
  providers: [
    UsersService,
    { provide: APP_GUARD, useClass: RolesGuard },  // global AND DI-aware
  ],
})
export class AppModule {}

app.useGlobalGuards(new X()) is fine for a dependency-free enhancer. The moment the enhancer needs to inject anything — Reflector, ConfigService, a repository — you must register it through the provider token: APP_GUARD, APP_INTERCEPTOR, APP_PIPE, or APP_FILTER. Those make the enhancer a real provider that Nest constructs, so its constructor dependencies resolve from the container instead of being null.

Failure modes seniors hit

AuthZ in a pipe, or a guard expecting a validated body. Because guards run before pipes, a guard sees the raw body — a DTO class isn’t instantiated, numbers are still strings. Authorization that depends on validated input belongs in the handler or a post-pipe interceptor, not the guard, and never in a pipe (a pipe transforms data, it isn’t an authorization boundary).

Expecting an interceptor to map errors. An interceptor can catch via catchError in its RxJS pipe, but the canonical error-to-response mapping is the exception filter (@Catch, catch(exception, host)). Doing both causes double-handling. And scope matters for what a filter catches: a guard throws at stage 2, before any method-scoped filter is in play, so only a higher-scoped (global) filter catches an exception thrown inside a guard.

Middleware reaching for handler metadata. Middleware runs before route resolution, so there is no ExecutionContext and no way to read @Roles() or any handler decorator. If you need handler metadata, you need a guard — that is precisely why guards exist as a distinct stage.