ExceptionFiltersContext

Kind: Class

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

Part of: Websockets

ExceptionFiltersContext builds and resolves WebSocket exception filters for gateway handlers. It combines method-level and global filter metadata into a WsExceptionsHandler, allowing WebSocket errors to be processed consistently through Nest’s exception-filter pipeline.

Extends: BaseExceptionFilterContext

Methods

Where it refuses work

• ExceptionFiltersContext stops the work with an early return when isEmpty(filters).

Diagram

mermaid
graph LR
  Gateway[WebSocket Gateway Handler] --> Context[ExceptionFiltersContext]
  Context --> Metadata[Exception Filter Metadata]
  Context --> GlobalFilters[Global / Request-Scoped Filters]
  Metadata --> Handler[WsExceptionsHandler]
  GlobalFilters --> Handler
  Handler --> Client[WebSocket Client Error Response]

Usage

ts
import { ExceptionFiltersContext } from '@nestjs/websockets';
import { NestContainer } from '@nestjs/core';
import { ApplicationConfig } from '@nestjs/core';

const container = new NestContainer();
const applicationConfig = new ApplicationConfig();

const exceptionFiltersContext = new ExceptionFiltersContext(
  container,
  applicationConfig,
);

const wsExceptionsHandler = exceptionFiltersContext.create(
  gatewayInstance,
  gatewayInstance.handleMessage,
  'ChatGatewayModule',
);

// Use the resolved handler when invoking a WebSocket gateway method.
wsExceptionsHandler.handle(
  new Error('Unable to process message'),
  host,
);

AI Coding Instructions

• Use create() when preparing a WebSocket gateway callback so method- and class-level exception filters are resolved before execution.
• Preserve filter ordering: custom filters are applied in reverse order to match Nest’s exception-filter execution behavior.
• Use getGlobalMetadata() when extending filter resolution logic; it includes configured global filters and request-scoped filters when applicable.
• Avoid bypassing WsExceptionsHandler for gateway errors, as doing so can skip custom filters and inconsistent client error serialization.

How it works

ExceptionFiltersContext

ExceptionFiltersContext is a public WebSocket exception-filter context builder. It extends BaseExceptionFilterContext and is constructed with a NestContainer, which the inherited implementation uses to resolve class-based filters from a module’s injectable collection. packages/websockets/context/exception-filters-context.ts:10-13 packages/core/exceptions/base-exception-filter-context.ts:14-16 packages/core/exceptions/base-exception-filter-context.ts:59-71

Relationships

• IMPORTS → EXCEPTION_FILTERS_METADATA
• IMPORTS → isEmpty
• IMPORTS → BaseExceptionFilterContext
• IMPORTS → NestContainer