WsExceptionFilter

Kind: Interface

Source: packages/common/interfaces/exceptions/ws-exception-filter.interface.ts

Part of: Common

Interface describing implementation of a Web Sockets exception filter.

WsExceptionFilter defines the contract for handling exceptions thrown during WebSocket message processing. Implementations receive the thrown exception and the current ArgumentsHost, allowing them to inspect the WebSocket client, request data, and emit an appropriate error response. Use this interface when creating custom filters for WebSocket gateways.

Diagram

mermaid
graph LR
  A[WebSocket Client Event] --> B[Gateway Handler]
  B -->|Throws exception| C[WsExceptionFilter.catch]
  C --> D[ArgumentsHost]
  D --> E[WebSocket Client]
  C --> F[Emit or return error response]
  F --> E

Usage

ts
import {
  ArgumentsHost,
  Catch,
  UseFilters,
  WsException,
  WsExceptionFilter,
  WebSocketGateway,
  SubscribeMessage,
} from '@nestjs/common';

@Catch(WsException)
export class ChatWsExceptionFilter implements WsExceptionFilter {
  catch(exception: WsException, host: ArgumentsHost) {
    const client = host.switchToWs().getClient();
    const error = exception.getError();

    client.emit('exception', {
      status: 'error',
      message: typeof error === 'string' ? error : 'Unable to process message',
    });
  }
}

@WebSocketGateway()
@UseFilters(new ChatWsExceptionFilter())
export class ChatGateway {
  @SubscribeMessage('send-message')
  sendMessage() {
    throw new WsException('Message delivery failed');
  }
}

AI Coding Instructions

• Implement a catch(exception, host) method that matches the WsExceptionFilter contract.
• Use host.switchToWs() to access the WebSocket client and incoming message data.
• Prefer handling WsException explicitly and safely normalize its error payload before sending it to clients.
• Emit a consistent error event, such as exception, so WebSocket clients can handle failures predictably.
• Register filters with @UseFilters() on a gateway or individual message handler as needed.

Used by

1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.

Imported by (1)

• ErrorPayload — packages/websockets/exceptions/base-ws-exception-filter.ts:11