NestJS Debugging Guide

This guide provides a systematic approach to debugging NestJS applications. Use the four-phase methodology below to efficiently identify and resolve issues.

Common Error Patterns

1. Dependency Resolution Errors

Error Message:

Nest can't resolve dependencies of the <ProviderName> (?). Please make sure that the argument <DependencyName> at index [0] is available in the <ModuleName> context.

Common Causes:

• Provider not added to module's providers array
• Missing @Injectable() decorator on service class
• Incorrect import/export between modules
• Typo in injection token name
• Missing forRoot()/forRootAsync() configuration

Solutions:

// Ensure provider is in the module
@Module({
  providers: [MyService], // Add missing provider here
  exports: [MyService],   // Export if used by other modules
})
export class MyModule {}

// Ensure @Injectable() decorator exists
@Injectable()
export class MyService {
  constructor(private readonly dependency: OtherService) {}
}

// For external modules, import the module not just the service
@Module({
  imports: [OtherModule], // Import the module
})
export class MyModule {}

2. Circular Dependency Errors

Error Message:

Nest cannot create the module instance. The module at index [X] of the imports array is undefined.

Common Causes:

• Two modules importing each other
• Two services depending on each other
• File-level circular imports (constants, types)

Solutions:

// Use forwardRef() for circular module dependencies
@Module({
  imports: [forwardRef(() => OtherModule)],
})
export class MyModule {}

// Use forwardRef() for circular service dependencies
@Injectable()
export class ServiceA {
  constructor(
    @Inject(forwardRef(() => ServiceB))
    private serviceB: ServiceB,
  ) {}
}

// Alternative: Extract shared logic to a third module
@Module({
  providers: [SharedService],
  exports: [SharedService],
})
export class SharedModule {}

3. Guard/Interceptor Issues

Error Message:

Cannot read property 'canActivate' of undefined
Cannot read property 'intercept' of undefined

Common Causes:

• Guard/Interceptor not properly registered
• Missing @UseGuards() or @UseInterceptors() decorator
• Incorrect scope (request-scoped vs singleton)
• Dependencies not available in guard/interceptor context

Solutions:

// Register globally in main.ts
app.useGlobalGuards(new AuthGuard());
app.useGlobalInterceptors(new LoggingInterceptor());

// Or register via module for DI support
@Module({
  providers: [
    {
      provide: APP_GUARD,
      useClass: AuthGuard,
    },
    {
      provide: APP_INTERCEPTOR,
      useClass: LoggingInterceptor,
    },
  ],
})
export class AppModule {}

// Controller-level registration
@UseGuards(AuthGuard)
@UseInterceptors(LoggingInterceptor)
@Controller('users')
export class UsersController {}

4. Pipe Validation Errors

Error Message:

An instance of an invalid class-validator value was provided
Validation failed (expected type)

Common Causes:

• Missing class-transformer or class-validator packages
• DTO not properly decorated with validation decorators
• ValidationPipe not configured correctly
• Transform option not enabled

Solutions:

// Enable ValidationPipe globally with proper options
app.useGlobalPipes(
  new ValidationPipe({
    whitelist: true,           // Strip non-whitelisted properties
    forbidNonWhitelisted: true, // Throw on extra properties
    transform: true,           // Auto-transform payloads to DTO instances
    transformOptions: {
      enableImplicitConversion: true,
    },
  }),
);

// Properly decorate DTOs
import { IsString, IsInt, Min, IsOptional } from 'class-validator';
import { Type } from 'class-transformer';

export class CreateUserDto {
  @IsString()
  name: string;

  @IsInt()
  @Min(0)
  @Type(() => Number)
  age: number;

  @IsOptional()
  @IsString()
  email?: string;
}

5. Microservice Communication Errors

Error Message:

There is no matching message handler defined in the remote service
Connection refused / ECONNREFUSED

Common Causes:

• Message pattern mismatch between client and server
• Transport configuration mismatch
• Service not connected or not running
• Serialization/deserialization issues

Solutions:

// Ensure matching patterns
// Server side
@MessagePattern({ cmd: 'get_user' })
async getUser(data: { id: number }) {
  return this.usersService.findOne(data.id);
}

// Client side - pattern must match exactly
const user = await this.client.send({ cmd: 'get_user' }, { id: 1 }).toPromise();

// Check transport configuration matches
// Server
const app = await NestFactory.createMicroservice<MicroserviceOptions>(
  AppModule,
  {
    transport: Transport.TCP,
    options: { host: '0.0.0.0', port: 3001 },
  },
);

// Client module
ClientsModule.register([
  {
    name: 'USER_SERVICE',
    transport: Transport.TCP,
    options: { host: 'localhost', port: 3001 },
  },
]);

6. WebSocket/Gateway Errors

Error Message:

Gateway is not defined
WebSocket connection failed

Common Causes:

• Missing @WebSocketGateway() decorator
• Gateway not added to module providers
• CORS issues with WebSocket connections
• Adapter not properly configured

Solutions:

// Properly configure gateway
@WebSocketGateway({
  cors: {
    origin: '*',
  },
  namespace: '/events',
})
export class EventsGateway implements OnGatewayConnection {
  @WebSocketServer()
  server: Server;

  handleConnection(client: Socket) {
    console.log('Client connected:', client.id);
  }

  @SubscribeMessage('message')
  handleMessage(client: Socket, payload: any): string {
    return 'Hello world!';
  }
}

// Add to module
@Module({
  providers: [EventsGateway],
})
export class EventsModule {}

// Configure adapter in main.ts if needed
import { IoAdapter } from '@nestjs/platform-socket.io';
app.useWebSocketAdapter(new IoAdapter(app));

Debugging Tools

1. NestJS Debug Mode

# Start with debug flag
nest start --debug --watch

# Or add to package.json
"start:debug": "nest start --debug --watch"

2. VS Code Debugger Configuration

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug NestJS",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "start:debug"],
      "console": "integratedTerminal",
      "restart": true,
      "autoAttachChildProcesses": true,
      "sourceMaps": true,
      "envFile": "${workspaceFolder}/.env"
    },
    {
      "type": "node",
      "request": "attach",
      "name": "Attach to NestJS",
      "port": 9229,
      "restart": true,
      "sourceMaps": true
    }
  ]
}

3. Docker Debug Configuration

# docker-compose.debug.yml
version: '3.8'
services:
  api:
    command: npm run start:debug
    ports:
      - "3000:3000"
      - "9229:9229"  # Debug port
    environment:
      - NODE_OPTIONS=--inspect=0.0.0.0:9229

4. Built-in Logger Service

import { Logger, Injectable } from '@nestjs/common';

@Injectable()
export class MyService {
  private readonly logger = new Logger(MyService.name);

  async doSomething() {
    this.logger.log('Processing started');
    this.logger.debug('Debug info', { data: someData });
    this.logger.warn('Warning message');
    this.logger.error('Error occurred', error.stack);
    this.logger.verbose('Verbose details');
  }
}

// Configure logger level in main.ts
const app = await NestFactory.create(AppModule, {
  logger: ['error', 'warn', 'log', 'debug', 'verbose'],
});

5. @nestjs/testing Utilities

import { Test, TestingModule } from '@nestjs/testing';
import { INestApplication } from '@nestjs/common';
import * as request from 'supertest';

describe('UsersController (e2e)', () => {
  let app: INestApplication;

  beforeEach(async () => {
    const moduleFixture: TestingModule = await Test.createTestingModule({
      imports: [AppModule],
    })
    .overrideProvider(UsersService)
    .useValue(mockUsersService)
    .compile();

    app = moduleFixture.createNestApplication();
    await app.init();
  });

  it('/users (GET)', () => {
    return request(app.getHttpServer())
      .get('/users')
      .expect(200)
      .expect({ data: [] });
  });
});

The Four Phases (NestJS-specific)

Phase 1: Gather Context

Before debugging, collect all relevant information:

# Check NestJS and dependency versions
npm list @nestjs/core @nestjs/common @nestjs/platform-express

# Check for peer dependency issues
npm ls 2>&1 | grep -i "peer dep"

# Review recent changes
git diff HEAD~5 --name-only | grep -E '\.(ts|json)$'

# Check environment configuration
cat .env | grep -v -E '^#|^$'

Key Questions:

• When did the error start occurring?
• What changes were made recently?
• Is this reproducible in all environments?
• Are there any relevant logs or stack traces?

Phase 2: Isolate the Problem

Narrow down the issue systematically:

// 1. Check module structure
import { Logger } from '@nestjs/common';

@Module({
  imports: [
    // Comment out imports one by one to isolate
    ConfigModule.forRoot(),
    // DatabaseModule,  // Try disabling
    // UsersModule,     // Try disabling
  ],
})
export class AppModule {
  constructor() {
    Logger.log('AppModule initialized');
  }
}

// 2. Add lifecycle logging
@Injectable()
export class MyService implements OnModuleInit, OnModuleDestroy {
  private readonly logger = new Logger(MyService.name);

  onModuleInit() {
    this.logger.log('MyService initialized');
  }

  onModuleDestroy() {
    this.logger.log('MyService destroyed');
  }
}

// 3. Test dependency injection manually
@Controller()
export class TestController {
  constructor(
    @Optional() private myService?: MyService,
  ) {
    console.log('MyService injected:', !!this.myService);
  }
}

Phase 3: Debug and Fix

Apply targeted debugging techniques:

// 1. For DI issues - check the module graph
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule, {
    logger: ['verbose'],  // Enable all logging
  });

  // Log all registered routes
  const server = app.getHttpServer();
  const router = server._events.request._router;
  console.log('Registered routes:', router.stack
    .filter(r => r.route)
    .map(r => `${Object.keys(r.route.methods)} ${r.route.path}`));

  await app.listen(3000);
}

// 2. For async configuration issues
@Module({
  imports: [
    ConfigModule.forRootAsync({
      useFactory: async () => {
        console.log('ConfigModule factory called');
        const config = await loadConfig();
        console.log('Config loaded:', config);
        return config;
      },
    }),
  ],
})
export class AppModule {}

// 3. For guard/interceptor debugging
@Injectable()
export class DebugGuard implements CanActivate {
  private readonly logger = new Logger(DebugGuard.name);

  canActivate(context: ExecutionContext): boolean {
    const request = context.switchToHttp().getRequest();
    this.logger.debug(`Guard checking: ${request.method} ${request.url}`);
    this.logger.debug(`Headers: ${JSON.stringify(request.headers)}`);
    this.logger.debug(`User: ${JSON.stringify(request.user)}`);
    return true;  // Allow through for debugging
  }
}

Phase 4: Verify and Document

Ensure the fix is complete and documented:

// 1. Write a test for the fixed issue
describe('UserService', () => {
  it('should resolve dependencies correctly', async () => {
    const module = await Test.createTestingModule({
      imports: [UsersModule],
    }).compile();

    const service = module.get<UsersService>(UsersService);
    expect(service).toBeDefined();
    expect(service.userRepository).toBeDefined();
  });
});

// 2. Add error handling to prevent recurrence
@Injectable()
export class RobustService {
  private readonly logger = new Logger(RobustService.name);

  async riskyOperation() {
    try {
      return await this.externalCall();
    } catch (error) {
      this.logger.error(`Operation failed: ${error.message}`, error.stack);
      throw new InternalServerErrorException('Operation failed');
    }
  }
}

// 3. Document in comments
/**
 * UserService handles user-related operations.
 *
 * IMPORTANT: This service depends on DatabaseModule being imported
 * before UsersModule in AppModule to avoid circular dependency issues.
 *
 * @see https://docs.nestjs.com/fundamentals/circular-dependency
 */
@Injectable()
export class UsersService {}

Quick Reference Commands

Debugging Commands

# Start in debug mode
npm run start:debug

# Start with increased heap memory
NODE_OPTIONS="--max-old-space-size=4096" npm run start:debug

# Run with verbose logging
LOG_LEVEL=verbose npm run start

# Debug specific module loading
DEBUG=nest:* npm run start

# Check TypeScript compilation
npx tsc --noEmit

# Validate module structure
npx nest info

Common Fixes

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Rebuild NestJS
npm run build
rm -rf dist && npm run build

# Clear cache
npm cache clean --force

# Check for duplicate packages
npm dedupe

# Update NestJS packages
npx npm-check-updates -u "@nestjs/*"
npm install

Inspection Commands

# List all modules and providers
npx nest info

# Check circular dependencies
npx madge --circular --extensions ts src/

# Analyze bundle size
npx source-map-explorer dist/main.js

# Check TypeScript config
npx tsc --showConfig

# Verify imports
npx ts-unused-exports tsconfig.json

Docker Debugging

# Access container shell
docker exec -it <container_id> sh

# View container logs
docker logs -f <container_id>

# Check container environment
docker exec <container_id> env

# Debug with docker compose
docker compose -f docker-compose.debug.yml up

# Attach to running container
docker attach <container_id>

Exception Filters for Better Error Handling

import {
  ExceptionFilter,
  Catch,
  ArgumentsHost,
  HttpException,
  HttpStatus,
  Logger,
} from '@nestjs/common';

@Catch()
export class AllExceptionsFilter implements ExceptionFilter {
  private readonly logger = new Logger(AllExceptionsFilter.name);

  catch(exception: unknown, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse();
    const request = ctx.getRequest();

    const status =
      exception instanceof HttpException
        ? exception.getStatus()
        : HttpStatus.INTERNAL_SERVER_ERROR;

    const message =
      exception instanceof HttpException
        ? exception.getResponse()
        : 'Internal server error';

    const errorResponse = {
      statusCode: status,
      timestamp: new Date().toISOString(),
      path: request.url,
      method: request.method,
      message: typeof message === 'string' ? message : (message as any).message,
    };

    this.logger.error(
      `${request.method} ${request.url} ${status}`,
      exception instanceof Error ? exception.stack : String(exception),
    );

    response.status(status).json(errorResponse);
  }
}

// Register globally
app.useGlobalFilters(new AllExceptionsFilter());

Performance Debugging

// 1. Add timing interceptor
@Injectable()
export class TimingInterceptor implements NestInterceptor {
  private readonly logger = new Logger(TimingInterceptor.name);

  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const now = Date.now();
    const request = context.switchToHttp().getRequest();

    return next.handle().pipe(
      tap(() => {
        const elapsed = Date.now() - now;
        this.logger.log(`${request.method} ${request.url} - ${elapsed}ms`);

        if (elapsed > 1000) {
          this.logger.warn(`Slow request: ${request.url} took ${elapsed}ms`);
        }
      }),
    );
  }
}

// 2. Profile database queries
import { Logger } from '@nestjs/common';

// In TypeORM configuration
{
  logging: ['query', 'error', 'warn'],
  logger: 'advanced-console',
  maxQueryExecutionTime: 1000,  // Log slow queries
}

Sources

• NestJS Official Documentation - Common Errors
• NestJS Official Documentation - Exception Filters
• NestJS Official Documentation - Logger
• Debugging NestJS in VSCode - Plain English
• Debugging NestJS Applications in VS Code - Medium
• Step-debugging Docker Compose NestJS services - Rob Allen
• NestJS Error Handling Patterns - Better Stack
• Error Handling in NestJS Best Practices - DEV Community
• 10 Common Mistakes to Avoid in NestJS - Medium
• Debugging Nest.js Applications - Rookout