Fix UnauthorizedException: Unauthorized in NestJS

This error occurs when a NestJS guard returns false or throws, blocking access to a protected route. Common causes include missing or invalid JWT tokens, expired sessions, or misconfigured guard logic. Fix it by verifying the token is sent correctly in the Authorization header and the guard validates it properly.

Reading the Stack Trace

Here's what each line means:

• at JwtAuthGuard.handleRequest (src/auth/jwt-auth.guard.ts:14:13): Your custom guard's handleRequest at line 14 threw UnauthorizedException because the JWT validation failed.
• at GuardsConsumer.tryActivate (node_modules/@nestjs/core/guards/guards-consumer.js:15:39): NestJS's guard execution pipeline invoked the guard before reaching the route handler.
• at RouterExplorer.executePipeline (node_modules/@nestjs/core/router/router-execution-context.js:173:23): The router pipeline executed guards before pipes and interceptors, blocking the request early.

Common Causes

// Client request missing Authorization header
fetch('/api/profile', { method: 'GET' });

const token = jwt.sign({ userId: 1 }, secret, { expiresIn: '1h' });
// Token used 2 hours later - expired

// Auth module uses 'old-secret' for signing
// JwtStrategy uses process.env.JWT_SECRET which is 'new-secret'

The Fix

Add public route support via a custom decorator so not every route requires authentication. Improve the error message by using passport's info object to explain why authentication failed (expired, malformed, missing).

import { Injectable, UnauthorizedException } from '@nestjs/common';
import { AuthGuard } from '@nestjs/passport';

@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {
  handleRequest(err, user) {
    if (err || !user) {
      throw new UnauthorizedException();
    }
    return user;
  }
}

import { Injectable, UnauthorizedException, ExecutionContext } from '@nestjs/common';
import { AuthGuard } from '@nestjs/passport';
import { Reflector } from '@nestjs/core';
import { IS_PUBLIC_KEY } from './public.decorator';

@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {
  constructor(private reflector: Reflector) {
    super();
  }

  canActivate(context: ExecutionContext) {
    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
      context.getHandler(),
      context.getClass(),
    ]);
    if (isPublic) return true;
    return super.canActivate(context);
  }

  handleRequest(err: any, user: any, info: any) {
    if (err || !user) {
      const message = info?.message || 'Invalid or missing authentication token';
      throw new UnauthorizedException(message);
    }
    return user;
  }
}

Testing the Fix

import { Test, TestingModule } from '@nestjs/testing';
import { JwtAuthGuard } from './jwt-auth.guard';
import { Reflector } from '@nestjs/core';
import { UnauthorizedException, ExecutionContext } from '@nestjs/common';

describe('JwtAuthGuard', () => {
  let guard: JwtAuthGuard;
  let reflector: Reflector;

  beforeEach(async () => {
    const module: TestingModule = await Test.createTestingModule({
      providers: [JwtAuthGuard, Reflector],
    }).compile();

    guard = module.get<JwtAuthGuard>(JwtAuthGuard);
    reflector = module.get<Reflector>(Reflector);
  });

  it('throws UnauthorizedException when user is null', () => {
    expect(() => guard.handleRequest(null, null, { message: 'jwt expired' }))
      .toThrow(UnauthorizedException);
  });

  it('returns user when authentication succeeds', () => {
    const user = { id: 1, email: 'test@example.com' };
    expect(guard.handleRequest(null, user, null)).toEqual(user);
  });

  it('includes info message in the exception', () => {
    expect(() => guard.handleRequest(null, null, { message: 'jwt expired' }))
      .toThrow('jwt expired');
  });
});

Run your tests:

npm test

Pushing Through CI/CD

git checkout -b fix/nestjs-guard-unauthorized,git add src/auth/jwt-auth.guard.ts src/auth/__tests__/jwt-auth.guard.spec.ts,git commit -m "fix: improve JWT guard error messages and add public route support",git push origin fix/nestjs-guard-unauthorized

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm test -- --coverage
      - run: npm run build

The Full Manual Process: 18 Steps

Here's every step you just went through to fix this one bug:

1. Notice the error alert or see it in your monitoring tool
2. Open the error dashboard and read the stack trace
3. Identify the file and line number from the stack trace
4. Open your IDE and navigate to the file
5. Read the surrounding code to understand context
6. Reproduce the error locally
7. Identify the root cause
8. Write the fix
9. Run the test suite locally
10. Fix any failing tests
11. Write new tests covering the edge case
12. Run the full test suite again
13. Create a new git branch
14. Commit and push your changes
15. Open a pull request
16. Wait for code review
17. Merge and deploy to production
18. Monitor production to confirm the error is resolved

Total time: 30-60 minutes. For one bug.

npm install bugstack-sdk

import { initBugStack } from 'bugstack-sdk'

initBugStack({ apiKey: process.env.BUGSTACK_API_KEY })

Deploying the Fix (Manual Path)

1. Verify the JWT secret is consistent between signing and verification.
2. Ensure clients send the Authorization: Bearer <token> header.
3. Add descriptive error messages to the guard's handleRequest.
4. Run tests to verify guard behavior for valid and invalid tokens.
5. Open a PR, merge after CI, and test authentication in staging.

Frequently Asked Questions