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.

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

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.

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

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

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 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:

The simplest guard that compiles and does something real:

Apply it to one route:

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.

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.

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.

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.

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.

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:

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().

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.

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.

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().

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.

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.

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.

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.

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

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.

▶️ Open the interactive playground →

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

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: