ExceptionFiltersContext

Kind: Class

Source: packages/microservices/context/exception-filters-context.ts

Part of: Microservices

ExceptionFiltersContext builds the RpcExceptionsHandler used to process exceptions thrown by microservice RPC handlers. It collects exception filters declared on controllers and handlers, combines them with global filter metadata, and configures the handler with the correct execution order.

Extends: BaseExceptionFilterContext

Methods

Where it refuses work

• ExceptionFiltersContext stops the work with an early return when isEmpty(filters).
• ExceptionFiltersContext stops the work with an early return when contextId === STATIC_CONTEXT && !inquirerId.

Diagram

mermaid
graph LR
  A[RPC request] --> B[Microservice handler]
  B -->|throws exception| C[RpcExceptionsHandler]
  D[ExceptionFiltersContext] -->|creates| C
  D -->|collects| E[Controller and method filters]
  D -->|gets| F[Global exception filters]
  E --> C
  F --> C
  C --> G[Custom exception response]

Usage

ts
import { Catch, ArgumentsHost } from '@nestjs/common';
import { RpcExceptionFilter } from '@nestjs/microservices';

@Catch()
class RpcErrorFilter implements RpcExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    return {
      status: 'error',
      message: exception instanceof Error ? exception.message : 'Unknown RPC error',
    };
  }
}

// ExceptionFiltersContext is created internally by Nest's microservice runtime.
// Registering filters through the application configuration makes them available
// when it creates the RpcExceptionsHandler for each RPC handler.
async function bootstrap() {
  const app = await NestFactory.createMicroservice(AppModule, {
    transport: Transport.TCP,
  });

  app.useGlobalFilters(new RpcErrorFilter());

  await app.listen();
}

AI Coding Instructions

• Treat ExceptionFiltersContext as framework infrastructure; register filters through decorators or app.useGlobalFilters() rather than constructing it in application code.
• Ensure custom RPC filters implement RpcExceptionFilter and return a value compatible with the active microservice transport.
• Preserve filter ordering when changing context creation logic; method- and controller-level filters must be applied consistently with global filters.
• Use getGlobalMetadata() when extending context behavior so request-scoped global filters are included alongside static global filters.

How it works

ExceptionFiltersContext is a public microservices context creator that extends BaseExceptionFilterContext. It receives a NestContainer for resolving filter classes and an ApplicationConfig for global filter registrations. [packages/microservices/context/exception-filters-context.ts:16-22]

Relationships

• IMPORTS → EXCEPTION_FILTERS_METADATA
• IMPORTS → Controller
• IMPORTS → isEmpty
• IMPORTS → ApplicationConfig
• IMPORTS → BaseExceptionFilterContext
• IMPORTS → STATIC_CONTEXT
• IMPORTS → NestContainer
• IMPORTS → InstanceWrapper