Guards, interceptors and exception filters

The lifecycle is the whole lesson

Every HTTP request in Nest walks the same ordered gauntlet before and after your handler runs. Knowing the order is not trivia — it tells you where each concern can sit and, just as importantly, what it can see when it runs.

The sequence: middleware → guards → interceptors (pre) → pipes → handler → interceptors (post) → exception filters (on a throw). A guard runs after middleware but before any interceptor or pipe. Pipes run after guards have already decided the request may proceed — so by the time a pipe transforms the body, authorization is settled. Interceptors are the only stage that runs twice: once on the way in (before the handler) and once on the way out (wrapping the response). And exception filters sit off to the side, catching anything thrown anywhere downstream.

Two subtleties separate seniors from the docs-skimmers. First, interceptors resolve outbound first-in-last-out: inbound they run global → controller → route, but the response unwinds route → controller → global, like nested function returns. Second, the filter is a catch-all sink — a pipe that throws, a guard that throws, a handler that throws, even an interceptor’s stream that errors all land in the same filter. That is why error formatting belongs there and nowhere else.

Guards: a yes/no decision, read from metadata

A guard implements CanActivate. It returns a boolean (or a Promise/Observable of one) — true lets the request through, false (or a thrown exception) stops it. This is the home of authentication and authorization. The guard receives an ExecutionContext, a superset of ArgumentsHost that also knows which handler and controller are about to run — which is exactly what you need to read route-level metadata.

The canonical pattern is a @Roles() decorator that stamps metadata onto a handler, plus a RolesGuard that reads it back via the Reflector:

import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { ROLES_KEY } from './roles.decorator';

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const required = this.reflector.getAllAndOverride<string[]>(ROLES_KEY, [
      context.getHandler(),
      context.getClass(),
    ]);
    if (!required) return true; // no @Roles() on this route -> open
    const { user } = context.switchToHttp().getRequest();
    return required.some((role) => user?.roles?.includes(role));
  }
}

getAllAndOverride reads the metadata from the handler first and falls back to the controller, so a route-level @Roles('admin') overrides a controller default. Throw ForbiddenException instead of returning false if you want a 403 with a message rather than a bare denial.

Interceptors: wrap the handler, on both sides

An interceptor’s intercept(context, next) runs code before the handler, then calls next.handle() — which returns an RxJS Observable of the eventual response — and can run code after by piping operators onto that stream. This dual position makes interceptors the right tool for anything that brackets the call: logging and timing, caching, response shaping, and timeouts.

import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Observable } from 'rxjs';
import { map, tap } from 'rxjs/operators';

@Injectable()
export class TransformInterceptor implements NestInterceptor {
  intercept(ctx: ExecutionContext, next: CallHandler): Observable<unknown> {
    const start = Date.now();
    return next.handle().pipe(
      tap(() => console.log(`took ${Date.now() - start}ms`)), // side-effect, no change to data
      map((data) => ({ data })),                              // reshape every response
    );
  }
}

tap is for side-effects that do not touch the payload (logging, metrics); map transforms the response body — here wrapping every handler’s return in { data: ... } so the whole API speaks one envelope. Because next.handle() is lazy, the pre-handler code runs synchronously when intercept is called, but nothing after next.handle() runs until the handler resolves. An interceptor can also short-circuit (return its own Observable without calling next.handle(), e.g. serving a cache hit) or catch downstream errors with the catchError operator.

Exception filters: shape the error, once

When anything in the chain throws, Nest’s built-in exception layer catches it and produces a response — HttpException and its subclasses map to their status code, anything else becomes a 500. A custom @Catch() filter lets you own that response shape globally instead of formatting errors by hand in every handler.

import { ExceptionFilter, Catch, ArgumentsHost, HttpException } from '@nestjs/common';

@Catch(HttpException)
export class HttpErrorFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const res = host.switchToHttp().getResponse();
    const status = exception.getStatus();
    res.status(status).json({
      statusCode: status,
      message: exception.getResponse(),
      timestamp: new Date().toISOString(),
    });
  }
}

@Catch(HttpException) narrows the filter to a type; @Catch() with no argument catches everything. Because the filter is the single sink for every throw in the pipeline, error formatting lives here and only here — a guard, pipe, or handler just throws the right exception and trusts the filter to render it.

Where does each concern go?

This is the senior judgment the whole lesson builds to. The mistake in the hook was not bad code — it was four concerns living in the wrong slot. Match the concern to the lifecycle stage:

Each of the four can be bound at three scopes: method (@UseGuards() on a handler), controller (the same decorator on the class), or global (app.useGlobalGuards() in bootstrap, or a provider token for DI-friendly globals). The rule of thumb: bind broad and override narrow — a global filter for the default error shape, a global ValidationPipe, an auth guard at controller level, and a @Roles() guard plus per-route metadata where the granular decision lives.