JwtAuthGuard 401 Response Behavior with Expired Tokens in NestJS 10.x

Direct Answers

1. Default response: HTTP 401 with a JSON body {"statusCode":401,"message":"Unauthorized"} — not an empty body.
2. Expired vs. malformed vs. missing: All three produce the identical default 401 response because the built-in guard discards passport-jwt's failure details and throws a generic UnauthorizedException.
3. Customization: The 401 payload cannot be changed through JwtModule configuration. You must extend AuthGuard('jwt'), apply a custom exception filter, or implement a completely custom guard.

Why the Default Behavior Is Uniform

NestJS 10.x's @nestjs/passport AuthGuard('jwt') wraps passport-jwt's JwtStrategy. When passport-jwt validates a token it distinguishes three failure modes internally:

• TokenExpiredError (expired)
• JsonWebTokenError (malformed/signature invalid)
• Missing Authorization header or no bearer token

The guard's default implementation catches any failure and throws new UnauthorizedException(). NestJS's built-in exception filter then serializes that to the standard {statusCode, message} shape. No token-specific detail reaches the client unless you intervene.

What JwtModule Actually Controls

JwtModule.register({ secret, signOptions, verifyOptions }) influences validation, not the HTTP response format:

• verifyOptions.ignoreExpiration: true disables expiry checks (token never expires) — do not use this to change response behavior.
• verifyOptions.clockTolerance adjusts leeway for clock drift.
• Server clock drift affects when exp is considered past due, but the response remains the same 401.

How to Differentiate or Customize the Response

Option A: Extend the Guard (Recommended)

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

@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {
  handleRequest(err: any, user: any, info: any, context: ExecutionContext) {
    if (err || !user) {
      // info contains passport-jwt's error (TokenExpiredError, JsonWebTokenError, etc.)
      const message = info?.name === 'TokenExpiredError' ? 'Token expired' : 'Unauthorized';
      throw new UnauthorizedException({ statusCode: 401, message, code: info?.name });
    }
    return user;
  }
}

Now expired tokens return {statusCode:401,message:"Token expired",code:"TokenExpiredError"} while others keep a generic message.

Option B: Global Exception Filter

Catch UnauthorizedException in a filter and reshape the response. You still cannot distinguish failure types unless the guard passes info into the exception (Option A does this).

Option C: Fully Custom Guard

Implement CanActivate and call passport-jwt directly for complete control.

Verification Steps (Run Once)

1. Register JwtModule with a secret.
2. Apply @UseGuards(AuthGuard('jwt')) to a test endpoint.
3. Send three requests:
   1. Valid token → 200
   2. Expired token (sign with exp in past) → inspect body
   3. Malformed token (tampered signature) → inspect body
   4. No Authorization header → inspect body
4. Confirm all three failures return identical {"statusCode":401,"message":"Unauthorized"} under your exact @nestjs/passport and passport-jwt versions.

Assumptions & Uncertainty

• Assumes NestJS 10.x, @nestjs/passport 10.x, passport-jwt 4.x. Minor version differences could alter the default message string.
• Global exception filters (e.g., HttpExceptionFilter) may already be reshaping the 401 in your project — verify before assuming the stock shape.
• The info object passed to handleRequest is documented but not guaranteed across passport-jwt upgrades; log it during development.

One Diagnostic Detail Needed

Does your application already register a global exception filter that catches UnauthorizedException? If yes, the default response you observe may already be customized, and the guard-extension approach (Option A) must coordinate with that filter.