---

name: nestjs-error-handling description: Implement Global Exception Filters and standard error formats in NestJS. Use when implementing global exception filters or standardizing error responses in NestJS. metadata: triggers: files: - '**/*.filter.ts' - 'main.ts' keywords: - ExceptionFilter - Catch - HttpException

NestJS Error Handling Standards

Priority: P1 (HIGH)

• Requirement: Centralize error formatting.
• Platform Agnostic: not import Request/Response from Express/Fastify types directly.
• Use: HttpAdapterHost to access underlying platform response methods.
• const { httpAdapter } = this.httpAdapterHost;
• Structure:
• Implement strictly typed error responses.
• Refer to API Standards for ApiErrorResponse.

 {
   "statusCode": 400,
   "message": "Validation failed",
   "error": "Bad Request",
   "timestamp": "ISO...",
   "path": "/users"
 }

Error Flow

1. Service: Throws specific or generic errors (e.g., EntityNotFoundError).
2. Interceptor: Maps low-level errors to HTTP Exceptions (e.g., catchError(err => throw new NotFoundException())).

• Why: Keeps Exception Filters focused on formatting, not business logic interpretation.

3. Global Filter: Formats final JSON response.

Built-in Exceptions

• Use: Throw NotFoundException, ForbiddenException, BadRequestException.
• Custom: Extend HttpException only for domain-specific failures that need specific status codes.

Logging

• Context: Always pass MyClass.name to Logger constructor.
• Levels:
• error: 500s (Stack trace required).
• warn: 400s (Client errors).

Security (Information Leakage)

• Production: NEVER expose stack traces in HTTP responses (process.env.NODE_ENV === 'production').
• Sanitization: Ensure ApiException payloads not leak internal file paths or raw variable dumps.

Anti-Patterns

• No stack traces in production: Gate stack exposure behind NODE_ENV === 'production' check.
• No Express types in filters: Use HttpAdapterHost for platform-agnostic error handling.
• No HttpException in services: Throw domain errors in services; let Interceptors map to HTTP exceptions.

Canonical response anchors

• Additional task-grounded exact anchors: sanitiz