debug-nestjs_skill

Overview

This skill diagnoses and resolves NestJS runtime problems with a systematic four-phase approach. It targets dependency injection failures, circular imports, guard/interceptor and pipe validation issues, microservice and WebSocket communication errors, and other Nest-specific runtime faults. Use it to quickly isolate root causes and apply proven fixes and checks.

How this skill works

The skill inspects common NestJS error patterns and walks through a structured workflow: gather context, isolate the failing component, apply targeted debugging fixes, and verify plus document the resolution. It provides concrete checks (module/provider configuration, decorator presence, forwardRef usage), runtime tools (debug flags, logger usage, VS Code/Docker debug setups), and commands to validate environment and dependencies.

When to use it

• When you see “Nest can't resolve dependencies” or provider injection errors
• If modules or services cause circular dependency failures or undefined imports
• When guards, interceptors, pipes, or decorators behave as undefined or misconfigured
• For microservice message pattern mismatches, connection refusals, or WebSocket gateway failures
• When runtime validation fails or DTO transformation is not working
• During CI/e2e test failures related to NestJS module wiring or lifecycle

Best practices

• Always register providers in the module and export them when consumed by other modules
• Use @Injectable() and correct injection tokens; import modules instead of services directly
• Use forwardRef() or extract shared functionality into a dedicated module to break cycles
• Enable ValidationPipe with transform and whitelist options; decorate DTOs with class-validator/class-transformer
• Add lifecycle logging (OnModuleInit/OnModuleDestroy) and use the built-in Logger for targeted traces
• Add tests and documentation after fixing issues to prevent regressions

Example use cases

• Resolve a provider-not-found error by checking module providers and exports, then re-run with verbose logger
• Break a circular dependency between ServiceA and ServiceB using forwardRef or moving shared logic to SharedModule
• Debug a failing WebSocket gateway by ensuring @WebSocketGateway, adding the provider to the module, and configuring the IoAdapter
• Fix microservice message failures by matching @MessagePattern payloads and transport options between client and server
• Address validation errors by installing class-validator/class-transformer and enabling ValidationPipe with transform and implicit conversion