name: NestJS Error Handling description: Global Exception Filters and standard error formats. metadata: labels: [nestjs, errors, filters] triggers: files: ['**/*.filter.ts', 'main.ts'] keywords: [ExceptionFilter, Catch, HttpException]

NestJS Error Handling Standards

Priority: P1 (OPERATIONAL)

Global error handling and exception management patterns.

• Requirement: Centralize error formatting.

• Platform Agnostic: Do not import Request/Response from Express/Fastify types directly.

  • Use: HttpAdapterHost to access the 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 the 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 the 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 do not leak internal file paths or raw variable dumps.