debug:nestjs

What this skill does

# 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:**
```typescript
// 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:**
```typescript
// 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:**
```typescript
// 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:**
```typescript
// 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:**
```typescript
// 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:**
```typescript
// 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

```bash
# 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`:
```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

```yaml
# 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

```typescript
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

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

describe('UsersC