ExternalExceptionFilter

Kind: Class

Source: packages/core/exceptions/external-exception-filter.ts

Part of: Core

ExternalExceptionFilter defines the exception-handling contract used to process errors raised outside the normal request flow. Implement its catch() method to inspect an exception, access the current execution context, and return either a response value or a promise.

Methods

Diagram

mermaid
graph LR
  A[Unhandled exception] --> B[ExternalExceptionFilter.catch]
  B --> C[ArgumentsHost]
  C --> D[Access transport context]
  B --> E[Create error response]
  E --> F[Return value or Promise]

Usage

ts
import type { ArgumentsHost } from '@nestjs/common';
import type { ExternalExceptionFilter } from '@nestjs/core';

class LoggingExceptionFilter implements ExternalExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    const response = host.switchToHttp().getResponse();

    console.error('Unhandled external exception:', exception);

    return response.status(500).json({
      statusCode: 500,
      message: 'Internal server error',
    });
  }
}

// Register the filter with the relevant application integration point.
const filter = new LoggingExceptionFilter();

AI Coding Instructions

• Implement catch() with the expected exception and ArgumentsHost parameters; it may return a value directly or a Promise.
• Use ArgumentsHost to select the active transport context, such as HTTP, RPC, or WebSocket, before writing a response.
• Avoid assuming every exception is an Error; safely handle strings, objects, and unknown thrown values.
• Preserve framework-specific response conventions, including status codes and response serialization.
• Log unexpected exceptions with useful context, but avoid exposing internal error details to clients.

How it works

ExternalExceptionFilter<T, R>

ExternalExceptionFilter is a generic exception-filter base class. Its catch method accepts an exception of type T and an ArgumentsHost, is declared to return R | Promise<R>, but always throws the received exception instead of returning normally. packages/core/exceptions/external-exception-filter.ts:3-6 packages/core/exceptions/external-exception-filter.ts:14

Relationships

• IMPORTS → ArgumentsHost
• IMPORTS → IntrinsicException
• IMPORTS → Logger