NestJS Guards: CanActivate, ExecutionContext & Reflector

A code review flags a "protected" admin endpoint. The controller has @UseGuards(RolesGuard) on the class, RolesGuard injects a UserService to check role hierarchy, and it's registered application-wide with app.useGlobalGuards(new RolesGuard(reflector, userService)) in main.ts. It looks careful. It is also broken: userService is undefined inside the guard, on every single request, and no test would have caught it because the app never crashed — it just let every request through the branch that assumes a user has no elevated role.

Nothing here is a typo. The guard class is correct. The decorator is correct. The one thing wrong is how the guard was registered — and until you know what a guard actually is to Nest's container, that line looks completely reasonable.

This is written against NestJS 12.0.x (verified September 2026, current @nestjs/core release, v12.0.4). The CanActivate interface, ExecutionContext, and Reflector covered here have been stable since well before v9 and are untouched by v12's ESM and Standard Schema changes — nothing in this article is version-fragile.

What you'll learn

By the end of this article you'll be able to:

• Explain what a guard actually is — a DI-instantiated class, not a function you happen to call canActivate
• Read and use ExecutionContext to get at the request, the handler, and the controller class from inside a guard
• Build a Reflector-backed @Roles() decorator and understand exactly why the method's metadata overrides the class's
• Register a global guard the right way (APP_GUARD) so it keeps its dependency injection
• Predict, for any combination of global/controller/method guards, the exact order they run in and what "all must pass" means

Who this is for

You've written a NestJS controller, used @UseGuards() at least once, and you know what @Injectable() does. If you haven't read the NestJS request lifecycle episode of this series, it's a useful map of where guards sit relative to middleware, interceptors, and pipes — but this article is self-contained.

Table of contents

• The problem: a guard that quietly can't do its job
• The mental model: a guard is a provider, not a function
• Stage 1: the smallest correct guard
• Stage 2: ExecutionContext, properly
• Stage 3: Reflector and a real @Roles() decorator
• Stage 4: registering a global guard without losing DI
• Stage 5: composing guards — order and "all must pass"
• Edge cases and gotchas
• Best practices
• FAQ
• Cheat sheet
• Key takeaways

The problem: a guard that quietly can't do its job

Here's the guard from the intro, in full:

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(
    private reflector: Reflector,
    private userService: UserService, // meant to check role hierarchy
  ) {}

  canActivate(context: ExecutionContext): boolean {
    const required = this.reflector.get<string[]>("roles", context.getHandler());
    if (!required) return true;
    const { user } = context.switchToHttp().getRequest();
    // userService is undefined here — this branch always throws or always no-ops
    return this.userService.hasAnyRole(user, required);
  }
}

And here's how it was wired up, because "global" sounded like the right word for "runs on every route":

// main.ts — looks reasonable, is quietly broken
const app = await NestFactory.create(AppModule);
app.useGlobalGuards(new RolesGuard(new Reflector(), /* userService? */ undefined));

app.useGlobalGuards() takes an instance. Nothing about that instance goes through Nest's dependency injection — you constructed it yourself, with new, outside any module, before the application's providers even exist to hand it a real UserService. Nest will happily call canActivate() on this object for every request. It just can't give it the dependency the guard was written to use.

The fix isn't a different guard. It's a different registration, covered in Stage 4. But to see why that fix works, you need the actual mental model of what a guard is.

The mental model: a guard is a provider, not a function

The mental model: a NestJS guard is an ordinary DI provider — the same kind of class as a service — that additionally implements one method, canActivate(context: ExecutionContext), which Nest calls immediately before it would otherwise invoke your route handler. If canActivate resolves to true, the request keeps moving toward interceptors, pipes, and the handler. If it resolves to false, or throws, the handler never runs and Nest hands the request straight to the exception-filter layer.

Three consequences fall out of that one sentence, and they're the three things the intro's bug got wrong:

1. A guard only gets real dependency injection if Nest constructs it. @UseGuards(RolesGuard) (passing the class) lets Nest instantiate it through the container, resolving its constructor arguments normally. new RolesGuard(...) (passing an instance you built) does not — you're on your own for every dependency.
2. A guard doesn't see "a request" in the abstract — it sees an ExecutionContext. That's a wrapper Nest builds fresh for every incoming call, giving the guard a uniform way to reach the underlying request and to ask "what handler and class is Nest about to invoke?" — which is exactly what a guard needs to look up route-specific metadata.
3. A guard's decision is binary, not additive. It either lets a request through or it doesn't. Anything more nuanced than "yes/no" — attaching data, transforming the body — is an interceptor's or a pipe's job, not a guard's.

Stage 1: the smallest correct guard

The simplest guard that compiles and does something real:

import { CanActivate, ExecutionContext, Injectable } from "@nestjs/common";

@Injectable()
export class AuthGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    const request = context.switchToHttp().getRequest();
    return Boolean(request.headers.authorization);
  }
}

Apply it to one route:

@UseGuards(AuthGuard)
@Get("profile")
getProfile(@Req() req: Request) {
  return req.user;
}

Key concept: canActivate can return boolean, Promise<boolean>, or Observable<boolean> — Nest awaits or subscribes to whichever you give it. A guard that calls a database or an external identity provider to check a session is completely normal; just make it async canActivate(...): Promise<boolean> and Nest will wait for it before deciding.

Stage 2: ExecutionContext, properly

ExecutionContext is the single argument every guard, interceptor, and exception filter receives, and it answers two different questions:

"What kind of call is this, and what's the underlying request object?" — via switchToHttp(), switchToRpc(), or switchToWs(). Most guards only ever call context.switchToHttp().getRequest(), but the same guard class can run in front of a WebSocket gateway or a microservice handler if you check context.getType() first and branch — that's what makes ExecutionContext a context, not just an HTTP request wrapper.

"Which handler and which class is Nest about to call?" — via context.getHandler() (the specific route method, as a function reference) and context.getClass() (the controller class). This half is what makes metadata-driven guards possible, because it's the only way a guard can ask "does this specific route carry a @Roles(...) decorator?" — the guard runs once per registration, but getHandler()/getClass() tell it which route it's currently deciding for.

canActivate(context: ExecutionContext): boolean {
  const handlerName = context.getHandler().name;      // e.g. "getProfile"
  const controllerName = context.getClass().name;     // e.g. "UsersController"
  const request = context.switchToHttp().getRequest();
  // ...
}

Key concept: getHandler() and getClass() return the raw function/class references, not strings — they exist so you can hand them to Reflector, which looks up metadata attached to those exact references. That's the bridge to Stage 3.

Stage 3: Reflector and a real @Roles() decorator

Hardcoding a role check per route doesn't scale, and neither does branching on handler.name — a rename breaks it silently. The idiomatic pattern is a custom decorator that attaches metadata, and a Reflector that reads it back inside a guard.

// roles.decorator.ts
import { SetMetadata } from "@nestjs/common";

export const ROLES_KEY = "roles";
export const Roles = (...roles: string[]) => SetMetadata(ROLES_KEY, roles);

// roles.guard.ts
import { CanActivate, ExecutionContext, Injectable } 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 || required.length === 0) return true; // no @Roles() = open route

    const { user } = context.switchToHttp().getRequest();
    return required.some((role) => user?.roles?.includes(role));
  }
}

@Controller("orders")
@Roles("editor") // class-level default
export class OrdersController {
  @Get()
  list() { /* requires "editor" — inherits the class default */ }

  @Delete(":id")
  @Roles("admin") // method-level override
  remove() { /* requires "admin" — this wins over the class's "editor" */ }
}

Key concept: getAllAndOverride(key, [handler, class]) checks the handler first, then the class, and returns the first one it finds — it does not merge arrays. That order in the array is why a method-level @Roles("admin") completely replaces the class-level @Roles("editor") rather than requiring both. If you actually want both handler and class metadata combined, Reflector also has getAllAndMerge(), which concatenates arrays instead of short-circuiting — reach for it explicitly when "either level can add a role" is the behavior you want.

Stage 4: registering a global guard without losing DI

Back to the intro's bug. app.useGlobalGuards(new RolesGuard(...)) builds the guard outside the container, so any constructor dependency has to be supplied by hand — which is exactly what went wrong. The fix is to register the guard as a provider, using the APP_GUARD injection token from @nestjs/core:

import { APP_GUARD } from "@nestjs/core";

@Module({
  providers: [
    RolesGuard,
    { provide: APP_GUARD, useClass: RolesGuard },
  ],
})
export class AppModule {}

Because RolesGuard is now a normal provider, Nest resolves its constructor the usual way — Reflector (and, in the intro's case, a real UserService) get injected correctly, module-scoped providers work, and Test.createTestingModule can overrideProvider(RolesGuard) in tests the same way it overrides any other dependency, as covered in this series' testing module episode. None of that is available to a guard built with new in main.ts.

Key concept: app.useGlobalGuards() still exists and still works for a guard with zero dependencies — it's not deprecated. The rule is narrower and easy to remember: the moment a guard's constructor needs anything Nest would normally inject, register it through APP_GUARD, not useGlobalGuards().

Stage 5: composing guards — order and "all must pass"

A single request can pass through guards registered at three different scopes at once: global (APP_GUARD, or useGlobalGuards()), controller (@UseGuards() on the class), and method (@UseGuards() on the handler). Nest runs them in that exact order — global, then controller, then method — and within one @UseGuards(A, B) call, in the order listed.

This composition is a logical AND, not a fallback chain: every guard in the sequence must return (or resolve to) true, or the request is rejected at the first one that doesn't. There's no "guard B can override guard A's denial" — a single false anywhere in the chain ends the request immediately, and every guard after it, plus every interceptor and pipe, is skipped entirely.

@UseGuards(ThrottleGuard, RolesGuard) // ThrottleGuard runs first
@Controller("orders")
export class OrdersController {}

If a global AuthGuard is also registered via APP_GUARD, the real order for any route on this controller is: AuthGuard → ThrottleGuard → RolesGuard → (method-level guards, if any) → interceptors → pipes → the handler.

Edge cases and gotchas

• A guard that throws vs. a guard that returns false. Returning false produces a generic 403 Forbidden. Throwing a specific exception — throw new UnauthorizedException("Session expired") — gives the client (and your logs) a far more useful signal, and is the idiomatic choice for anything beyond "just deny it."
• Reflector needs the exact same metadata key everywhere. SetMetadata(ROLES_KEY, ...) and reflector.getAllAndOverride(ROLES_KEY, ...) must use the identical string (or, better, the same exported constant). A typo in one spot means the guard silently sees undefined and treats the route as unrestricted — this fails open, which is the worst direction for an auth check to fail.
• getAllAndOverride vs getAllAndMerge. Covered in Stage 3, but worth repeating because it's the single most common Reflector mistake: reach for getAllAndOverride when a method should be able to fully replace a class default, and getAllAndMerge when both levels should contribute.
• WebSocket and microservice guards need a type check. context.switchToHttp() throws if the current call isn't actually HTTP. A guard meant to run across transports should branch on context.getType() ("http", "ws", "rpc") before picking which switchTo*() to call.
• A denied guard skips the "before" half of interceptors too. Interceptors run after guards, so a rejected request never reaches even the setup code in an interceptor — only the exception-filter layer sees it.

Best practices

• Keep guards to yes/no authorization decisions. If you find yourself mutating the request object inside a guard, that logic usually belongs in middleware (before routing) or an interceptor (after the handler is chosen) instead.
• Prefer metadata-driven guards over hardcoded checks. A @Roles()/Reflector pair scales to new routes with zero changes to the guard itself; an if (handler.name === "remove") branch doesn't.
• Register anything with a dependency via APP_GUARD, never new Guard(). It's the difference between a guard that's testable and overridable, and one that silently can't be either.
• Fail closed, not open. If a metadata lookup comes back undefined because of a wiring mistake, decide what that should mean deliberately (usually: deny), rather than letting !required accidentally mean "allow everyone."
• One guard, one concern. A ThrottleGuard and a RolesGuard composed via @UseGuards(ThrottleGuard, RolesGuard) are each easier to test and reuse than one guard doing both jobs.

FAQ

Do guards run before or after middleware?

After. Middleware runs first and doesn't know which controller or handler will end up serving the request; guards run once routing has resolved to a specific handler, which is what lets a guard call context.getHandler().

Can a guard inject a service?

Yes, as long as Nest constructs the guard — via @UseGuards(SomeGuard) (the class) or an APP_GUARD provider. A guard instance you build yourself with new gets none of Nest's dependency injection.

Can I use @UseGuards() more than once on the same controller?

Yes — @UseGuards(A, B, C) runs them in that order, and you can also stack a class-level @UseGuards() with a method-level one; both apply, in the global → controller → method order described in Stage 5.

What does a guard returning false actually send to the client?

A 403 Forbidden by default, handled by Nest's built-in exception layer. Throw a specific HttpException subclass from inside the guard if you need a different status code or a custom error body.

Is Reflector only for guards?

No — interceptors and custom decorators use it too, for the same reason: reading metadata attached to a handler or class via SetMetadata. Guards are just its most common consumer, because "does this route require X" is the canonical authorization question.

Cheat sheet

// A guard is a provider that implements CanActivate.
@Injectable()
export class MyGuard implements CanActivate {
  constructor(private reflector: Reflector) {} // real DI, if registered correctly

  canActivate(ctx: ExecutionContext): boolean | Promise<boolean> {
    const req = ctx.switchToHttp().getRequest();       // the underlying request
    const handler = ctx.getHandler();                  // the exact route method
    const controller = ctx.getClass();                 // the controller class
    return true; // or false, or throw a specific HttpException
  }
}

// Metadata decorator + read-back
export const ROLES_KEY = "roles";
export const Roles = (...roles: string[]) => SetMetadata(ROLES_KEY, roles);
// method metadata wins over class metadata:
reflector.getAllAndOverride<string[]>(ROLES_KEY, [ctx.getHandler(), ctx.getClass()]);
// both levels contribute instead:
reflector.getAllAndMerge<string[]>(ROLES_KEY, [ctx.getHandler(), ctx.getClass()]);

// Registration — pick based on whether the guard has dependencies
@UseGuards(MyGuard)              // per-route or per-controller, always through DI
app.useGlobalGuards(new MyGuard()); // global, but NO dependency injection
{ provide: APP_GUARD, useClass: MyGuard } // global, WITH dependency injection

Execution order for one request: global → controller → method, each one an AND — the first false (or thrown exception) stops the chain immediately.

Key takeaways

• A guard is a DI provider with a canActivate(context: ExecutionContext) method — not a bare function, and not free of the container's rules.
• ExecutionContext gives a guard the underlying request (via switchToHttp()/switchToWs()/switchToRpc()) and the exact handler/class Nest is about to invoke (via getHandler()/getClass()).
• Reflector.getAllAndOverride() reads metadata attached with a custom decorator, checking the method before the class, and returns the first match — use getAllAndMerge() when you want both to contribute instead.
• app.useGlobalGuards(new G()) skips dependency injection entirely; use the APP_GUARD provider token for any global guard with constructor dependencies.
• Guards compose as global → controller → method, and it's a strict AND: any single false or thrown exception stops the request before it reaches the next guard, any interceptor, or the handler.

Ending

The guard from the intro wasn't wrong about what it wanted to check — it was wrong about how it was born. new RolesGuard(...) and { provide: APP_GUARD, useClass: RolesGuard } compile to the same class doing the same check, and only one of them lets Nest's container do its job. That's the whole lesson of guards: they look like plain functions with a canActivate name, but every guarantee they can offer — real dependencies, testability, metadata lookups through ExecutionContext — depends on Nest actually building them. Next time a "protected" route turns out not to be, check the registration line before you touch the guard's logic.

What's the strangest guard bug you've chased down — a missing dependency, a metadata key typo, or something else? Drop it in the comments.

🎮 Try it yourself

▶️ Open the interactive playground →

Runs right in your browser — poke at it and watch the concept react live.

🧠 Test yourself

Think it clicked? Take the 7-question quiz →

Instant feedback, a hint on every question, and an explanation for each answer — right or wrong.

🚀 Want more like this? Every guide, playground, and quiz lives on bestpractic.org — open it and sign up free so the next one finds you.

Thanks for reading! Let's stay connected:

• ⭐ GitHub — follow me and star the projects: github.com/parsajiravand
• 💬 Discord — join the frontend best-practices community: discord.gg/d9KRhuAwQ
• 📸 Instagram — frontend best practices, daily: @bestpractice___