Troubleshooting

Things break. Here's how to fix them.

"Cannot read property 'username' of undefined"

Problem: You're accessing user data but the user object is undefined.

Cause: Missing @Authentication() decorator.

// ❌ Missing decorator
@Get('profile')
getProfile(@CognitoUser() user: CognitoJwtPayload) {
  return user.username;  // user is undefined
}

// ✅ Add decorator
@Get('profile')
@Authentication()
getProfile(@CognitoUser() user: CognitoJwtPayload) {
  return user.username;
}

"Token signature verification failed"

Problem: JWT verification fails.

Possible causes:

Wrong User Pool ID

// Check your config
CognitoAuthModule.register({
  jwtVerifier: {
    userPoolId: 'us-east-1_XXXXX',  // ← Wrong region or ID
    clientId: 'your-client-id',
    tokenUse: 'access',
  },
})

Token from different User Pool

Your backend expects tokens from User Pool A, but your frontend sends tokens from User Pool B.

Malformed token

The token is corrupted or not a valid JWT. Test it at jwt.io.

"Module not found: @nestjs-cognito/auth"

Problem: Package not installed.

Fix:

pnpm add @nestjs-cognito/auth
# or
npm install @nestjs-cognito/auth

Decorators not working

Problem: @Authentication() doesn't protect routes.

Causes:

Module not imported

// ❌ Missing import
@Module({
  controllers: [UserController],
})
export class AppModule {}

// ✅ Import CognitoAuthModule
@Module({
  imports: [
    CognitoAuthModule.register({
      jwtVerifier: {
        userPoolId: 'us-east-1_xxxxx',
        clientId: 'your-client-id',
        tokenUse: 'access',
      },
    }),
  ],
  controllers: [UserController],
})
export class AppModule {}

Using decorators before module initialization

Make sure CognitoAuthModule is imported in the same module or a parent module.

"Cannot find module '@nestjs-cognito/core'"

Problem: Peer dependency not installed.

Fix:

pnpm add @nestjs-cognito/core

Token works in Postman but not in browser

Problem: CORS or cookie issues.

For cookies:

Backend: Allow credentials

app.enableCors({
  origin: 'http://localhost:3000',
  credentials: true,
});

Frontend: Include credentials

fetch('/api/protected', {
  credentials: 'include',
});

For headers:

Make sure the browser sends the Authorization header:

fetch('/api/protected', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

Groups not working

Problem: @Authorization(['admin']) doesn't restrict access.

Causes:

Groups not in token

Check the token at jwt.io. Look for cognito:groups claim. If it's missing, the user doesn't belong to any groups in Cognito.

Wrong token type

Groups are in ID tokens, not access tokens. Use ID tokens for group-based authorization.

CognitoAuthModule.register({
  jwtVerifier: {
    userPoolId: 'us-east-1_xxxxx',
    clientId: 'your-client-id',
    tokenUse: 'id',  // ← Use ID tokens
  },
})

"CognitoTokenTypeMismatchError"

Problem: You're using @CognitoIdUser() but sending an access token.

Fix: Either:

Send the correct token type
Use @CognitoUser() instead (works with both)

// ✅ Flexible
@Get('profile')
@Authentication()
getProfile(@CognitoUser() user: CognitoJwtPayload) {
  return user;
}

Tests failing with "Cannot verify token"

Problem: Tests fail because they try to verify real tokens.

Fix: Use the testing module with mocks.

import { CognitoTestingModule } from '@nestjs-cognito/testing';

beforeAll(async () => {
  const module = await Test.createTestingModule({
    imports: [
      CognitoTestingModule.register({}, {
        enabled: true,
        user: {
          username: 'test-user',
          email: 'test@example.com',
          groups: ['users'],
        },
      }),
      AppModule,
    ],
  }).compile();
});

Slow authentication

Problem: First request takes several seconds.

Cause: JWKS keys are fetched on first request.

Solution: This is normal. Subsequent requests are fast because keys are cached. If it's a problem:

Warm up the cache on startup
Use a CDN or cache layer
Pre-fetch JWKS keys

Token extraction not working

Problem: Custom token extractor doesn't find the token.

Debug:

export class CustomExtractor implements CognitoJwtExtractor {
  hasAuthenticationInfo(request: any): boolean {
    console.log('Request headers:', request.headers);  // ← Debug
    return Boolean(request.headers['x-custom-token']);
  }

  getAuthorizationToken(request: any): string | null {
    const token = request.headers['x-custom-token'];
    console.log('Extracted token:', token);  // ← Debug
    return token || null;
  }
}

TypeScript errors

Problem: Type errors with decorators or user objects.

Fix: Import types from the right package.

import type { CognitoJwtPayload } from '@nestjs-cognito/core';

// Not from @nestjs-cognito/auth

Getting 500 instead of 401

Problem: Server crashes instead of returning 401.

Cause: Unhandled exception in guard or token verification.

Fix: Check logs. Usually:

Missing configuration (User Pool ID, Client ID)
Network error fetching JWKS keys
Malformed configuration

WebSocket authentication not working

Problem: WebSocket connections fail authentication.

Common issues:

Token in wrong place

// ❌ Wrong
const socket = io('http://localhost:3000', {
  query: { token }
});

// ✅ Correct
const socket = io('http://localhost:3000', {
  extraHeaders: {
    authorization: `Bearer ${token}`
  }
});

Not checking token on connection

@WebSocketGateway()
export class Gateway implements OnGatewayConnection {
  constructor(
    @InjectCognitoJwtVerifier()
    private readonly jwtVerifier: CognitoJwtVerifier
  ) {}

  async handleConnection(client: Socket) {
    const token = client.handshake.headers.authorization?.replace('Bearer ', '');

    if (!token) {
      client.disconnect();
      return;
    }

    try {
      const payload = await this.jwtVerifier.verify(token);
      client.data.user = payload;
    } catch (error) {
      client.disconnect();
    }
  }
}

Still stuck?

Check GitHub issues: github.com/Lokicoule/nestjs-cognito/issues
Enable debug logs:

// Enable NestJS debug logs
const app = await NestFactory.create(AppModule, {
  logger: ['debug'],
});

Verify your token: Paste it at jwt.io and check:
- Valid JSON structure
- iss matches your User Pool
- exp is in the future
- Required claims are present