Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

A NestJS route behind the JWT guard always answers 401

Error{"message":"Unauthorized","statusCode":401}

Short answer

The guard answers 401 when Passport finds no token, cannot verify it, or the token is expired. Send the token as an Authorization Bearer header, make the signing and verifying secret identical, check the expiry, and make sure the guard names the same strategy you registered.

  • Applies to NestJS 11, @nestjs/passport 11, @nestjs/jwt 11, passport-jwt 4, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Call the protected route with curl and the exact token, so you see the answer without the client app in the way.

    curl -i http://localhost:3000/profile -H "Authorization: Bearer <access_token>"
  2. 2Match what you see, then jump to its fix

    1. 1The route answers 401 only from your client, and the curl call above worksThe token is not sent as a Bearer headerFix
    2. 2401 on a fresh token that has not expiredThe secret used to sign differs from the one used to verifyFix
    3. 3401 appears some time after login, and works again after a new loginThe token has expiredFix
    4. 4401 on every request, and validate() is never calledThe guard names a different strategy than the one registeredFix

What does the error look like?

  • {"message":"Unauthorized","statusCode":401}

Cause 1 of 4

The token is not sent as a Bearer header

1Check

The strategy reads the token with ExtractJwt.fromAuthHeaderAsBearerToken(), so the header must be Authorization: Bearer <token>, with one space and no quotes around the token.

curl -i http://localhost:3000/profile

2Fix

Send the header in exactly that form from the client, or change jwtFromRequest if you pass the token another way.

fetch('/profile', {
  headers: { Authorization: `Bearer ${accessToken}` },
});

3Verify

The route returns your profile data.

curl -i http://localhost:3000/profile -H "Authorization: Bearer <access_token>"

Confirmed by docs.nestjs.com

Did this fix it?

Cause 2 of 4

The secret used to sign differs from the one used to verify

1Check

The strategy's secretOrKey must be the same secret that JwtModule signs with. An environment variable that is empty or loaded later in one place gives a mismatch.

grep -rn "secret" src

2Fix

Use one shared constant or ConfigService value in both JwtModule.register and the strategy's super() call.

// jwt.strategy.ts
super({
  jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
  ignoreExpiration: false,
  secretOrKey: jwtConstants.secret,
});

3Verify

Log in again to get a new token and call the route.

curl -i http://localhost:3000/profile -H "Authorization: Bearer <new_token>"

Confirmed by docs.nestjs.com

Did this fix it?

Cause 3 of 4

The token has expired

1Check

Decode the payload and compare the exp claim (seconds since 1970) with the current time. The Nest guide's sample lifetime is 60 seconds.

date +%s

2Fix

Set a lifetime that fits your app in signOptions, and refresh tokens before they run out.

JwtModule.register({
  secret: jwtConstants.secret,
  signOptions: { expiresIn: '15m' },
})

3Verify

A token from a new login keeps working past the old limit.

curl -i http://localhost:3000/profile -H "Authorization: Bearer <new_token>"

Confirmed by docs.nestjs.com

Did this fix it?

Cause 4 of 4

The guard names a different strategy than the one registered

1Check

AuthGuard('jwt') looks up the strategy registered as jwt. The strategy class must extend PassportStrategy(Strategy) from passport-jwt and be in the module's providers.

grep -rn "AuthGuard\|PassportStrategy\|providers:" src

2Fix

Keep the default name, or pass the same name in both places, and add the strategy to providers.

@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {}

@Module({ providers: [AuthService, JwtStrategy] })
export class AuthModule {}

3Verify

A request with a valid token reaches the controller and request.user is set.

curl -i http://localhost:3000/profile -H "Authorization: Bearer <access_token>"

Confirmed by docs.nestjs.com

Did this fix it?

How do I stop it coming back?

  • Keep the secret in one config value and read it in both the signing and the verifying code.
  • Return the user object from validate(): what it returns becomes request.user.
  • Test the protected route with curl after every change to the auth module.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

NestJS GraphQL cannot work out the output type of a field or query

Cannot determine a GraphQL output type for the "<name>". Make sure your class is decorated with an appropriate decorator.

In code-first mode Nest reads TypeScript types through decorators, and arrays, promises and unions disappear at runtime.

2 causes, each with a fix

Back end

IntelliJ IDEA breakpoints are ignored in a NestJS app

No 'Debugger listening' line appears when the NestJS app starts

IntelliJ can only debug a NestJS app when the Node.js process runs with the inspector on and the IDE attaches to its port.

4 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.