feat(nestjs): Support WebSocket errors in SentryGlobalFilter

dev-packages/e2e-tests/test-applications/nestjs-websockets/src/app.gateway.ts

@@ -1,13 +1,21 @@
-import { SubscribeMessage, WebSocketGateway, MessageBody } from '@nestjs/websockets';
+import { UseFilters } from '@nestjs/common';
+import { MessageBody, SubscribeMessage, WebSocketGateway, WsException } from '@nestjs/websockets';
 import * as Sentry from '@sentry/nestjs';
+import { SentryGlobalFilter } from '@sentry/nestjs/setup';
 
+@UseFilters(new SentryGlobalFilter())
 @WebSocketGateway()
 export class AppGateway {
  @SubscribeMessage('test-exception')
  handleTestException() {
  throw new Error('This is an exception in a WebSocket handler');
  }
 
+ @SubscribeMessage('test-ws-exception')
+ handleWsException() {
+ throw new WsException('Expected WebSocket exception');
+ }
+
  @SubscribeMessage('test-manual-capture')
  handleManualCapture() {
  try {

dev-packages/e2e-tests/test-applications/nestjs-websockets/tests/errors.test.ts

@@ -22,16 +22,39 @@ test('Captures manually reported error in WebSocket gateway handler', async ({ b
  socket.disconnect();
 });
 
+test('Automatically captures unexpected errors in WebSocket gateway handlers', async ({ baseURL }) => {
+ const errorPromise = waitForError('nestjs-websockets', event => {
+ return event.exception?.values?.[0]?.value === 'This is an exception in a WebSocket handler';
+ });
+
+ const socket = io(baseURL!);
+ await new Promise<void>(resolve => socket.on('connect', resolve));
+
+ socket.emit('test-exception', {});
+
+ const error = await errorPromise;
+
+ expect(error.exception?.values).toHaveLength(1);
+ expect(error.exception?.values?.[0]?.type).toBe('Error');
+ expect(error.exception?.values?.[0]?.value).toBe('This is an exception in a WebSocket handler');
+ expect(error.exception?.values?.[0]?.mechanism).toEqual({
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ });
+
+ socket.disconnect();
+});
+
 // There is no good mechanism to verify that an event was NOT sent to Sentry.
-// The idea here is that we first send a message that triggers an exception which won't be auto-captured,
+// The idea here is that we first send a message that triggers an expected exception which won't be auto-captured,
 // and then send a message that triggers a manually captured error which will be sent to Sentry.
 // If the manually captured error arrives, we can deduce that the first exception was not sent,
 // because Socket.IO guarantees message ordering: https://socket.io/docs/v4/delivery-guarantees
-test('Does not automatically capture exceptions in WebSocket gateway handler', async ({ baseURL }) => {
+test('Does not automatically capture expected WebSocket exceptions', async ({ baseURL }) => {
  let errorEventOccurred = false;
 
  waitForError('nestjs-websockets', event => {
- if (!event.type && event.exception?.values?.[0]?.value === 'This is an exception in a WebSocket handler') {
+ if (!event.type && event.exception?.values?.[0]?.value === 'Expected WebSocket exception') {
  errorEventOccurred = true;
  }
 
@@ -45,7 +68,7 @@ test('Does not automatically capture exceptions in WebSocket gateway handler', a
  const socket = io(baseURL!);
  await new Promise<void>(resolve => socket.on('connect', resolve));
 
- socket.emit('test-exception', {});
+ socket.emit('test-ws-exception', {});
  socket.emit('test-manual-capture', {});
  await manualCapturePromise;
 

packages/nestjs/src/helpers.ts

@@ -25,10 +25,24 @@ export function isExpectedError(exception: unknown): boolean {
  return true;
  }
 
- // RpcException
- if (typeof ex.getError === 'function' && typeof ex.initMessage === 'function') {
+ if (isWsOrRpcException(exception)) {
  return true;
  }
 
  return false;
 }
+
+/**
+ * Determines if the exception is a WsException or RpcException, which have the same shape.
+ * Both have `getError()` and `initMessage()` methods.
+ *
+ * We use duck-typing to avoid importing from `@nestjs/websockets` or `@nestjs/microservices`.
+ */
+export function isWsOrRpcException(exception: unknown): boolean {
+ if (typeof exception !== 'object' || exception === null) {
+ return false;
+ }
+
+ const ex = exception as Record<string, unknown>;
+ return typeof ex.getError === 'function' && typeof ex.initMessage === 'function';
+}

packages/nestjs/src/setup.ts

@@ -10,7 +10,7 @@ import { Catch, Global, HttpException, Injectable, Logger, Module } from '@nestj
 import { APP_INTERCEPTOR, BaseExceptionFilter } from '@nestjs/core';
 import { captureException, debug, getDefaultIsolationScope, getIsolationScope } from '@sentry/core';
 import type { Observable } from 'rxjs';
-import { isExpectedError } from './helpers';
+import { isExpectedError, isWsOrRpcException } from './helpers';
 
 // Partial extract of FastifyRequest interface
 // https://github.com/fastify/fastify/blob/87f9f20687c938828f1138f91682d568d2a31e53/types/request.d.ts#L41
@@ -152,6 +152,33 @@ class SentryGlobalFilter extends BaseExceptionFilter {
  return;
  }
 
+ if (contextType === 'ws') {
+ if (!isExpectedError(exception)) {
+ captureException(exception, {
+ mechanism: {
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ },
+ });
+ }
+
+ const client = host.switchToWs().getClient<{ emit?: (event: string, data: unknown) => void }>();
+
+ if (isWsOrRpcException(exception)) {
+ const result = (exception as { getError: () => unknown }).getError();
+ const response = typeof result === 'object' && result !== null ? result : { status: 'error', message: result };
+ client.emit?.('exception', response);
+ return;
+ }
+
+ if (exception instanceof Error) {
+ this._logger.error(exception.message, exception.stack);
+ }
+
+ client.emit?.('exception', { status: 'error', message: 'Internal server error' });
+ return;
+ }
+
  // HTTP exceptions
  if (!isExpectedError(exception)) {
  captureException(exception, {

packages/nestjs/test/sentry-global-filter.test.ts

@@ -8,6 +8,7 @@ import { SentryGlobalFilter } from '../src/setup';
 
 vi.mock('../src/helpers', () => ({
  isExpectedError: vi.fn(),
+ isWsOrRpcException: vi.fn(),
 }));
 
 vi.mock('@sentry/core', () => ({
@@ -27,6 +28,7 @@ describe('SentryGlobalFilter', () => {
  let mockLoggerError: any;
  let mockLoggerWarn: any;
  let isExpectedErrorMock: any;
+ let isWsOrRpcExceptionMock: any;
 
  beforeEach(() => {
  vi.clearAllMocks();
@@ -57,6 +59,7 @@ describe('SentryGlobalFilter', () => {
  mockCaptureException = vi.spyOn(SentryCore, 'captureException').mockReturnValue('mock-event-id');
 
  isExpectedErrorMock = vi.mocked(Helpers.isExpectedError).mockImplementation(() => false);
+ isWsOrRpcExceptionMock = vi.mocked(Helpers.isWsOrRpcException).mockImplementation(() => false);
  });
 
  describe('HTTP context', () => {
@@ -237,4 +240,86 @@ describe('SentryGlobalFilter', () => {
  expect(mockCaptureException).not.toHaveBeenCalled();
  });
  });
+
+ describe('WebSocket context', () => {
+ let mockEmit: ReturnType<typeof vi.fn>;
+
+ beforeEach(() => {
+ mockEmit = vi.fn();
+ vi.mocked(mockArgumentsHost.getType).mockReturnValue('ws');
+ vi.mocked(mockArgumentsHost.switchToWs).mockReturnValue({
+ getClient: () => ({ emit: mockEmit }),
+ getData: vi.fn(),
+ getPattern: vi.fn(),
+ });
+ });
+
+ it('captures unexpected errors and emits a generic error response', () => {
+ const error = new Error('Test WebSocket error');
+
+ filter.catch(error, mockArgumentsHost);
+
+ expect(mockCaptureException).toHaveBeenCalledWith(error, {
+ mechanism: {
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ },
+ });
+ expect(mockLoggerError).toHaveBeenCalledWith(error.message, error.stack);
+ expect(mockEmit).toHaveBeenCalledWith('exception', {
+ status: 'error',
+ message: 'Internal server error',
+ });
+ });
+
+ it('does not capture expected WebSocket exceptions and emits their response', () => {
+ isExpectedErrorMock.mockReturnValueOnce(true);
+ isWsOrRpcExceptionMock.mockReturnValueOnce(true);
+ const exception = {
+ getError: () => 'Expected WebSocket exception',
+ initMessage: vi.fn(),
+ };
+
+ filter.catch(exception, mockArgumentsHost);
+
+ expect(mockCaptureException).not.toHaveBeenCalled();
+ expect(mockEmit).toHaveBeenCalledWith('exception', {
+ status: 'error',
+ message: 'Expected WebSocket exception',
+ });
+ });
+
+ it('does not capture HTTP exceptions and emits a generic error response', () => {
+ isExpectedErrorMock.mockReturnValueOnce(true);
+ const exception = new HttpException('Bad request', HttpStatus.BAD_REQUEST);
+
+ filter.catch(exception, mockArgumentsHost);
+
+ expect(mockCaptureException).not.toHaveBeenCalled();
+ expect(mockLoggerError).toHaveBeenCalledWith(exception.message, exception.stack);
+ expect(mockEmit).toHaveBeenCalledWith('exception', {
+ status: 'error',
+ message: 'Internal server error',
+ });
+ });
+
+ it('captures unexpected errors when the WebSocket client cannot emit', () => {
+ vi.mocked(mockArgumentsHost.switchToWs).mockReturnValue({
+ getClient: () => ({}),
+ getData: vi.fn(),
+ getPattern: vi.fn(),
+ });
+ const error = new Error('WebSocket adapter without emit');
+
+ filter.catch(error, mockArgumentsHost);
+
+ expect(mockCaptureException).toHaveBeenCalledWith(error, {
+ mechanism: {
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ },
+ });
+ expect(mockLoggerError).toHaveBeenCalledWith(error.message, error.stack);
+ });
+ });
 });

dev-packages/e2e-tests/test-applications/nestjs-websockets/src/app.gateway.ts

@@ -1,13 +1,21 @@
-import { SubscribeMessage, WebSocketGateway, MessageBody } from '@nestjs/websockets';
+import { UseFilters } from '@nestjs/common';
+import { MessageBody, SubscribeMessage, WebSocketGateway, WsException } from '@nestjs/websockets';
 import * as Sentry from '@sentry/nestjs';
+import { SentryGlobalFilter } from '@sentry/nestjs/setup';
 
+@UseFilters(new SentryGlobalFilter())
 @WebSocketGateway()
 export class AppGateway {
  @SubscribeMessage('test-exception')
  handleTestException() {
  throw new Error('This is an exception in a WebSocket handler');
  }
 
+ @SubscribeMessage('test-ws-exception')
+ handleWsException() {
+ throw new WsException('Expected WebSocket exception');
+ }
+
  @SubscribeMessage('test-manual-capture')
  handleManualCapture() {
  try {

dev-packages/e2e-tests/test-applications/nestjs-websockets/tests/errors.test.ts

@@ -22,16 +22,39 @@ test('Captures manually reported error in WebSocket gateway handler', async ({ b
  socket.disconnect();
 });
 
+test('Automatically captures unexpected errors in WebSocket gateway handlers', async ({ baseURL }) => {
+ const errorPromise = waitForError('nestjs-websockets', event => {
+ return event.exception?.values?.[0]?.value === 'This is an exception in a WebSocket handler';
+ });
+
+ const socket = io(baseURL!);
+ await new Promise<void>(resolve => socket.on('connect', resolve));
+
+ socket.emit('test-exception', {});
+
+ const error = await errorPromise;
+
+ expect(error.exception?.values).toHaveLength(1);
+ expect(error.exception?.values?.[0]?.type).toBe('Error');
+ expect(error.exception?.values?.[0]?.value).toBe('This is an exception in a WebSocket handler');
+ expect(error.exception?.values?.[0]?.mechanism).toEqual({
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ });
+
+ socket.disconnect();
+});
+
 // There is no good mechanism to verify that an event was NOT sent to Sentry.
-// The idea here is that we first send a message that triggers an exception which won't be auto-captured,
+// The idea here is that we first send a message that triggers an expected exception which won't be auto-captured,
 // and then send a message that triggers a manually captured error which will be sent to Sentry.
 // If the manually captured error arrives, we can deduce that the first exception was not sent,
 // because Socket.IO guarantees message ordering: https://socket.io/docs/v4/delivery-guarantees
-test('Does not automatically capture exceptions in WebSocket gateway handler', async ({ baseURL }) => {
+test('Does not automatically capture expected WebSocket exceptions', async ({ baseURL }) => {
  let errorEventOccurred = false;
 
  waitForError('nestjs-websockets', event => {
- if (!event.type && event.exception?.values?.[0]?.value === 'This is an exception in a WebSocket handler') {
+ if (!event.type && event.exception?.values?.[0]?.value === 'Expected WebSocket exception') {
  errorEventOccurred = true;
  }
 
@@ -45,7 +68,7 @@ test('Does not automatically capture exceptions in WebSocket gateway handler', a
  const socket = io(baseURL!);
  await new Promise<void>(resolve => socket.on('connect', resolve));
 
- socket.emit('test-exception', {});
+ socket.emit('test-ws-exception', {});
  socket.emit('test-manual-capture', {});
  await manualCapturePromise;
 

packages/nestjs/src/helpers.ts

@@ -25,10 +25,24 @@ export function isExpectedError(exception: unknown): boolean {
  return true;
  }
 
- // RpcException
- if (typeof ex.getError === 'function' && typeof ex.initMessage === 'function') {
+ if (isWsOrRpcException(exception)) {
  return true;
  }
 
  return false;
 }
+
+/**
+ * Determines if the exception is a WsException or RpcException, which have the same shape.
+ * Both have `getError()` and `initMessage()` methods.
+ *
+ * We use duck-typing to avoid importing from `@nestjs/websockets` or `@nestjs/microservices`.
+ */
+export function isWsOrRpcException(exception: unknown): boolean {
+ if (typeof exception !== 'object' || exception === null) {
+ return false;
+ }
+
+ const ex = exception as Record<string, unknown>;
+ return typeof ex.getError === 'function' && typeof ex.initMessage === 'function';
+}

packages/nestjs/src/setup.ts

@@ -10,7 +10,7 @@ import { Catch, Global, HttpException, Injectable, Logger, Module } from '@nestj
 import { APP_INTERCEPTOR, BaseExceptionFilter } from '@nestjs/core';
 import { captureException, debug, getDefaultIsolationScope, getIsolationScope } from '@sentry/core';
 import type { Observable } from 'rxjs';
-import { isExpectedError } from './helpers';
+import { isExpectedError, isWsOrRpcException } from './helpers';
 
 // Partial extract of FastifyRequest interface
 // https://github.com/fastify/fastify/blob/87f9f20687c938828f1138f91682d568d2a31e53/types/request.d.ts#L41
@@ -152,6 +152,33 @@ class SentryGlobalFilter extends BaseExceptionFilter {
  return;
  }
 
+ if (contextType === 'ws') {
+ if (!isExpectedError(exception)) {
+ captureException(exception, {
+ mechanism: {
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ },
+ });
+ }
+
+ const client = host.switchToWs().getClient<{ emit?: (event: string, data: unknown) => void }>();
+
+ if (isWsOrRpcException(exception)) {
+ const result = (exception as { getError: () => unknown }).getError();
+ const response = typeof result === 'object' && result !== null ? result : { status: 'error', message: result };
+ client.emit?.('exception', response);
+ return;
+ }
+
+ if (exception instanceof Error) {
+ this._logger.error(exception.message, exception.stack);
+ }
+
+ client.emit?.('exception', { status: 'error', message: 'Internal server error' });
+ return;
+ }
+
  // HTTP exceptions
  if (!isExpectedError(exception)) {
  captureException(exception, {

packages/nestjs/test/sentry-global-filter.test.ts

@@ -8,6 +8,7 @@ import { SentryGlobalFilter } from '../src/setup';
 
 vi.mock('../src/helpers', () => ({
  isExpectedError: vi.fn(),
+ isWsOrRpcException: vi.fn(),
 }));
 
 vi.mock('@sentry/core', () => ({
@@ -27,6 +28,7 @@ describe('SentryGlobalFilter', () => {
  let mockLoggerError: any;
  let mockLoggerWarn: any;
  let isExpectedErrorMock: any;
+ let isWsOrRpcExceptionMock: any;
 
  beforeEach(() => {
  vi.clearAllMocks();
@@ -57,6 +59,7 @@ describe('SentryGlobalFilter', () => {
  mockCaptureException = vi.spyOn(SentryCore, 'captureException').mockReturnValue('mock-event-id');
 
  isExpectedErrorMock = vi.mocked(Helpers.isExpectedError).mockImplementation(() => false);
+ isWsOrRpcExceptionMock = vi.mocked(Helpers.isWsOrRpcException).mockImplementation(() => false);
  });
 
  describe('HTTP context', () => {
@@ -237,4 +240,86 @@ describe('SentryGlobalFilter', () => {
  expect(mockCaptureException).not.toHaveBeenCalled();
  });
  });
+
+ describe('WebSocket context', () => {
+ let mockEmit: ReturnType<typeof vi.fn>;
+
+ beforeEach(() => {
+ mockEmit = vi.fn();
+ vi.mocked(mockArgumentsHost.getType).mockReturnValue('ws');
+ vi.mocked(mockArgumentsHost.switchToWs).mockReturnValue({
+ getClient: () => ({ emit: mockEmit }),
+ getData: vi.fn(),
+ getPattern: vi.fn(),
+ });
+ });
+
+ it('captures unexpected errors and emits a generic error response', () => {
+ const error = new Error('Test WebSocket error');
+
+ filter.catch(error, mockArgumentsHost);
+
+ expect(mockCaptureException).toHaveBeenCalledWith(error, {
+ mechanism: {
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ },
+ });
+ expect(mockLoggerError).toHaveBeenCalledWith(error.message, error.stack);
+ expect(mockEmit).toHaveBeenCalledWith('exception', {
+ status: 'error',
+ message: 'Internal server error',
+ });
+ });
+
+ it('does not capture expected WebSocket exceptions and emits their response', () => {
+ isExpectedErrorMock.mockReturnValueOnce(true);
+ isWsOrRpcExceptionMock.mockReturnValueOnce(true);
+ const exception = {
+ getError: () => 'Expected WebSocket exception',
+ initMessage: vi.fn(),
+ };
+
+ filter.catch(exception, mockArgumentsHost);
+
+ expect(mockCaptureException).not.toHaveBeenCalled();
+ expect(mockEmit).toHaveBeenCalledWith('exception', {
+ status: 'error',
+ message: 'Expected WebSocket exception',
+ });
+ });
+
+ it('does not capture HTTP exceptions and emits a generic error response', () => {
+ isExpectedErrorMock.mockReturnValueOnce(true);
+ const exception = new HttpException('Bad request', HttpStatus.BAD_REQUEST);
+
+ filter.catch(exception, mockArgumentsHost);
+
+ expect(mockCaptureException).not.toHaveBeenCalled();
+ expect(mockLoggerError).toHaveBeenCalledWith(exception.message, exception.stack);
+ expect(mockEmit).toHaveBeenCalledWith('exception', {
+ status: 'error',
+ message: 'Internal server error',
+ });
+ });
+
+ it('captures unexpected errors when the WebSocket client cannot emit', () => {
+ vi.mocked(mockArgumentsHost.switchToWs).mockReturnValue({
+ getClient: () => ({}),
+ getData: vi.fn(),
+ getPattern: vi.fn(),
+ });
+ const error = new Error('WebSocket adapter without emit');
+
+ filter.catch(error, mockArgumentsHost);
+
+ expect(mockCaptureException).toHaveBeenCalledWith(error, {
+ mechanism: {
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ },
+ });
+ expect(mockLoggerError).toHaveBeenCalledWith(error.message, error.stack);
+ });
+ });
 });

dev-packages/e2e-tests/test-applications/nestjs-websockets/src/app.gateway.ts

@@ -1,13 +1,21 @@
-import { SubscribeMessage, WebSocketGateway, MessageBody } from '@nestjs/websockets';
+import { UseFilters } from '@nestjs/common';
+import { MessageBody, SubscribeMessage, WebSocketGateway, WsException } from '@nestjs/websockets';
 import * as Sentry from '@sentry/nestjs';
+import { SentryGlobalFilter } from '@sentry/nestjs/setup';
 
+@UseFilters(new SentryGlobalFilter())
 @WebSocketGateway()
 export class AppGateway {
  @SubscribeMessage('test-exception')
  handleTestException() {
  throw new Error('This is an exception in a WebSocket handler');
  }
 
+ @SubscribeMessage('test-ws-exception')
+ handleWsException() {
+ throw new WsException('Expected WebSocket exception');
+ }
+
  @SubscribeMessage('test-manual-capture')
  handleManualCapture() {
  try {

dev-packages/e2e-tests/test-applications/nestjs-websockets/tests/errors.test.ts

@@ -22,16 +22,39 @@ test('Captures manually reported error in WebSocket gateway handler', async ({ b
  socket.disconnect();
 });
 
+test('Automatically captures unexpected errors in WebSocket gateway handlers', async ({ baseURL }) => {
+ const errorPromise = waitForError('nestjs-websockets', event => {
+ return event.exception?.values?.[0]?.value === 'This is an exception in a WebSocket handler';
+ });
+
+ const socket = io(baseURL!);
+ await new Promise<void>(resolve => socket.on('connect', resolve));
+
+ socket.emit('test-exception', {});
+
+ const error = await errorPromise;
+
+ expect(error.exception?.values).toHaveLength(1);
+ expect(error.exception?.values?.[0]?.type).toBe('Error');
+ expect(error.exception?.values?.[0]?.value).toBe('This is an exception in a WebSocket handler');
+ expect(error.exception?.values?.[0]?.mechanism).toEqual({
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ });
+
+ socket.disconnect();
+});
+
 // There is no good mechanism to verify that an event was NOT sent to Sentry.
-// The idea here is that we first send a message that triggers an exception which won't be auto-captured,
+// The idea here is that we first send a message that triggers an expected exception which won't be auto-captured,
 // and then send a message that triggers a manually captured error which will be sent to Sentry.
 // If the manually captured error arrives, we can deduce that the first exception was not sent,
 // because Socket.IO guarantees message ordering: https://socket.io/docs/v4/delivery-guarantees
-test('Does not automatically capture exceptions in WebSocket gateway handler', async ({ baseURL }) => {
+test('Does not automatically capture expected WebSocket exceptions', async ({ baseURL }) => {
  let errorEventOccurred = false;
 
  waitForError('nestjs-websockets', event => {
- if (!event.type && event.exception?.values?.[0]?.value === 'This is an exception in a WebSocket handler') {
+ if (!event.type && event.exception?.values?.[0]?.value === 'Expected WebSocket exception') {
  errorEventOccurred = true;
  }
 
@@ -45,7 +68,7 @@ test('Does not automatically capture exceptions in WebSocket gateway handler', a
  const socket = io(baseURL!);
  await new Promise<void>(resolve => socket.on('connect', resolve));
 
- socket.emit('test-exception', {});
+ socket.emit('test-ws-exception', {});
  socket.emit('test-manual-capture', {});
  await manualCapturePromise;
 

packages/nestjs/src/helpers.ts

@@ -25,10 +25,24 @@ export function isExpectedError(exception: unknown): boolean {
  return true;
  }
 
- // RpcException
- if (typeof ex.getError === 'function' && typeof ex.initMessage === 'function') {
+ if (isWsOrRpcException(exception)) {
  return true;
  }
 
  return false;
 }
+
+/**
+ * Determines if the exception is a WsException or RpcException, which have the same shape.
+ * Both have `getError()` and `initMessage()` methods.
+ *
+ * We use duck-typing to avoid importing from `@nestjs/websockets` or `@nestjs/microservices`.
+ */
+export function isWsOrRpcException(exception: unknown): boolean {
+ if (typeof exception !== 'object' || exception === null) {
+ return false;
+ }
+
+ const ex = exception as Record<string, unknown>;
+ return typeof ex.getError === 'function' && typeof ex.initMessage === 'function';
+}

packages/nestjs/src/setup.ts

@@ -10,7 +10,7 @@ import { Catch, Global, HttpException, Injectable, Logger, Module } from '@nestj
 import { APP_INTERCEPTOR, BaseExceptionFilter } from '@nestjs/core';
 import { captureException, debug, getDefaultIsolationScope, getIsolationScope } from '@sentry/core';
 import type { Observable } from 'rxjs';
-import { isExpectedError } from './helpers';
+import { isExpectedError, isWsOrRpcException } from './helpers';
 
 // Partial extract of FastifyRequest interface
 // https://github.com/fastify/fastify/blob/87f9f20687c938828f1138f91682d568d2a31e53/types/request.d.ts#L41
@@ -152,6 +152,33 @@ class SentryGlobalFilter extends BaseExceptionFilter {
  return;
  }
 
+ if (contextType === 'ws') {
+ if (!isExpectedError(exception)) {
+ captureException(exception, {
+ mechanism: {
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ },
+ });
+ }
+
+ const client = host.switchToWs().getClient<{ emit?: (event: string, data: unknown) => void }>();
+
+ if (isWsOrRpcException(exception)) {
+ const result = (exception as { getError: () => unknown }).getError();
+ const response = typeof result === 'object' && result !== null ? result : { status: 'error', message: result };
+ client.emit?.('exception', response);
+ return;
+ }
+
+ if (exception instanceof Error) {
+ this._logger.error(exception.message, exception.stack);
+ }
+
+ client.emit?.('exception', { status: 'error', message: 'Internal server error' });
+ return;
+ }
+
  // HTTP exceptions
  if (!isExpectedError(exception)) {
  captureException(exception, {

packages/nestjs/test/sentry-global-filter.test.ts

@@ -8,6 +8,7 @@ import { SentryGlobalFilter } from '../src/setup';
 
 vi.mock('../src/helpers', () => ({
  isExpectedError: vi.fn(),
+ isWsOrRpcException: vi.fn(),
 }));
 
 vi.mock('@sentry/core', () => ({
@@ -27,6 +28,7 @@ describe('SentryGlobalFilter', () => {
  let mockLoggerError: any;
  let mockLoggerWarn: any;
  let isExpectedErrorMock: any;
+ let isWsOrRpcExceptionMock: any;
 
  beforeEach(() => {
  vi.clearAllMocks();
@@ -57,6 +59,7 @@ describe('SentryGlobalFilter', () => {
  mockCaptureException = vi.spyOn(SentryCore, 'captureException').mockReturnValue('mock-event-id');
 
  isExpectedErrorMock = vi.mocked(Helpers.isExpectedError).mockImplementation(() => false);
+ isWsOrRpcExceptionMock = vi.mocked(Helpers.isWsOrRpcException).mockImplementation(() => false);
  });
 
  describe('HTTP context', () => {
@@ -237,4 +240,86 @@ describe('SentryGlobalFilter', () => {
  expect(mockCaptureException).not.toHaveBeenCalled();
  });
  });
+
+ describe('WebSocket context', () => {
+ let mockEmit: ReturnType<typeof vi.fn>;
+
+ beforeEach(() => {
+ mockEmit = vi.fn();
+ vi.mocked(mockArgumentsHost.getType).mockReturnValue('ws');
+ vi.mocked(mockArgumentsHost.switchToWs).mockReturnValue({
+ getClient: () => ({ emit: mockEmit }),
+ getData: vi.fn(),
+ getPattern: vi.fn(),
+ });
+ });
+
+ it('captures unexpected errors and emits a generic error response', () => {
+ const error = new Error('Test WebSocket error');
+
+ filter.catch(error, mockArgumentsHost);
+
+ expect(mockCaptureException).toHaveBeenCalledWith(error, {
+ mechanism: {
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ },
+ });
+ expect(mockLoggerError).toHaveBeenCalledWith(error.message, error.stack);
+ expect(mockEmit).toHaveBeenCalledWith('exception', {
+ status: 'error',
+ message: 'Internal server error',
+ });
+ });
+
+ it('does not capture expected WebSocket exceptions and emits their response', () => {
+ isExpectedErrorMock.mockReturnValueOnce(true);
+ isWsOrRpcExceptionMock.mockReturnValueOnce(true);
+ const exception = {
+ getError: () => 'Expected WebSocket exception',
+ initMessage: vi.fn(),
+ };
+
+ filter.catch(exception, mockArgumentsHost);
+
+ expect(mockCaptureException).not.toHaveBeenCalled();
+ expect(mockEmit).toHaveBeenCalledWith('exception', {
+ status: 'error',
+ message: 'Expected WebSocket exception',
+ });
+ });
+
+ it('does not capture HTTP exceptions and emits a generic error response', () => {
+ isExpectedErrorMock.mockReturnValueOnce(true);
+ const exception = new HttpException('Bad request', HttpStatus.BAD_REQUEST);
+
+ filter.catch(exception, mockArgumentsHost);
+
+ expect(mockCaptureException).not.toHaveBeenCalled();
+ expect(mockLoggerError).toHaveBeenCalledWith(exception.message, exception.stack);
+ expect(mockEmit).toHaveBeenCalledWith('exception', {
+ status: 'error',
+ message: 'Internal server error',
+ });
+ });
+
+ it('captures unexpected errors when the WebSocket client cannot emit', () => {
+ vi.mocked(mockArgumentsHost.switchToWs).mockReturnValue({
+ getClient: () => ({}),
+ getData: vi.fn(),
+ getPattern: vi.fn(),
+ });
+ const error = new Error('WebSocket adapter without emit');
+
+ filter.catch(error, mockArgumentsHost);
+
+ expect(mockCaptureException).toHaveBeenCalledWith(error, {
+ mechanism: {
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ },
+ });
+ expect(mockLoggerError).toHaveBeenCalledWith(error.message, error.stack);
+ });
+ });
 });

dev-packages/e2e-tests/test-applications/nestjs-websockets/src/app.gateway.ts

@@ -1,13 +1,21 @@
-import { SubscribeMessage, WebSocketGateway, MessageBody } from '@nestjs/websockets';
+import { UseFilters } from '@nestjs/common';
+import { MessageBody, SubscribeMessage, WebSocketGateway, WsException } from '@nestjs/websockets';
 import * as Sentry from '@sentry/nestjs';
+import { SentryGlobalFilter } from '@sentry/nestjs/setup';
 
+@UseFilters(new SentryGlobalFilter())
 @WebSocketGateway()
 export class AppGateway {
  @SubscribeMessage('test-exception')
  handleTestException() {
  throw new Error('This is an exception in a WebSocket handler');
  }
 
+ @SubscribeMessage('test-ws-exception')
+ handleWsException() {
+ throw new WsException('Expected WebSocket exception');
+ }
+
  @SubscribeMessage('test-manual-capture')
  handleManualCapture() {
  try {

dev-packages/e2e-tests/test-applications/nestjs-websockets/tests/errors.test.ts

@@ -22,16 +22,39 @@ test('Captures manually reported error in WebSocket gateway handler', async ({ b
  socket.disconnect();
 });
 
+test('Automatically captures unexpected errors in WebSocket gateway handlers', async ({ baseURL }) => {
+ const errorPromise = waitForError('nestjs-websockets', event => {
+ return event.exception?.values?.[0]?.value === 'This is an exception in a WebSocket handler';
+ });
+
+ const socket = io(baseURL!);
+ await new Promise<void>(resolve => socket.on('connect', resolve));
+
+ socket.emit('test-exception', {});
+
+ const error = await errorPromise;
+
+ expect(error.exception?.values).toHaveLength(1);
+ expect(error.exception?.values?.[0]?.type).toBe('Error');
+ expect(error.exception?.values?.[0]?.value).toBe('This is an exception in a WebSocket handler');
+ expect(error.exception?.values?.[0]?.mechanism).toEqual({
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ });
+
+ socket.disconnect();
+});
+
 // There is no good mechanism to verify that an event was NOT sent to Sentry.
-// The idea here is that we first send a message that triggers an exception which won't be auto-captured,
+// The idea here is that we first send a message that triggers an expected exception which won't be auto-captured,
 // and then send a message that triggers a manually captured error which will be sent to Sentry.
 // If the manually captured error arrives, we can deduce that the first exception was not sent,
 // because Socket.IO guarantees message ordering: https://socket.io/docs/v4/delivery-guarantees
-test('Does not automatically capture exceptions in WebSocket gateway handler', async ({ baseURL }) => {
+test('Does not automatically capture expected WebSocket exceptions', async ({ baseURL }) => {
  let errorEventOccurred = false;
 
  waitForError('nestjs-websockets', event => {
- if (!event.type && event.exception?.values?.[0]?.value === 'This is an exception in a WebSocket handler') {
+ if (!event.type && event.exception?.values?.[0]?.value === 'Expected WebSocket exception') {
  errorEventOccurred = true;
  }
 
@@ -45,7 +68,7 @@ test('Does not automatically capture exceptions in WebSocket gateway handler', a
  const socket = io(baseURL!);
  await new Promise<void>(resolve => socket.on('connect', resolve));
 
- socket.emit('test-exception', {});
+ socket.emit('test-ws-exception', {});
  socket.emit('test-manual-capture', {});
  await manualCapturePromise;
 

packages/nestjs/src/helpers.ts

@@ -25,10 +25,24 @@ export function isExpectedError(exception: unknown): boolean {
  return true;
  }
 
- // RpcException
- if (typeof ex.getError === 'function' && typeof ex.initMessage === 'function') {
+ if (isWsOrRpcException(exception)) {
  return true;
  }
 
  return false;
 }
+
+/**
+ * Determines if the exception is a WsException or RpcException, which have the same shape.
+ * Both have `getError()` and `initMessage()` methods.
+ *
+ * We use duck-typing to avoid importing from `@nestjs/websockets` or `@nestjs/microservices`.
+ */
+export function isWsOrRpcException(exception: unknown): boolean {
+ if (typeof exception !== 'object' || exception === null) {
+ return false;
+ }
+
+ const ex = exception as Record<string, unknown>;
+ return typeof ex.getError === 'function' && typeof ex.initMessage === 'function';
+}

packages/nestjs/src/setup.ts

@@ -10,7 +10,7 @@ import { Catch, Global, HttpException, Injectable, Logger, Module } from '@nestj
 import { APP_INTERCEPTOR, BaseExceptionFilter } from '@nestjs/core';
 import { captureException, debug, getDefaultIsolationScope, getIsolationScope } from '@sentry/core';
 import type { Observable } from 'rxjs';
-import { isExpectedError } from './helpers';
+import { isExpectedError, isWsOrRpcException } from './helpers';
 
 // Partial extract of FastifyRequest interface
 // https://github.com/fastify/fastify/blob/87f9f20687c938828f1138f91682d568d2a31e53/types/request.d.ts#L41
@@ -152,6 +152,33 @@ class SentryGlobalFilter extends BaseExceptionFilter {
  return;
  }
 
+ if (contextType === 'ws') {
+ if (!isExpectedError(exception)) {
+ captureException(exception, {
+ mechanism: {
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ },
+ });
+ }
+
+ const client = host.switchToWs().getClient<{ emit?: (event: string, data: unknown) => void }>();
+
+ if (isWsOrRpcException(exception)) {
+ const result = (exception as { getError: () => unknown }).getError();
+ const response = typeof result === 'object' && result !== null ? result : { status: 'error', message: result };
+ client.emit?.('exception', response);
+ return;
+ }
+
+ if (exception instanceof Error) {
+ this._logger.error(exception.message, exception.stack);
+ }
+
+ client.emit?.('exception', { status: 'error', message: 'Internal server error' });
+ return;
+ }
+
  // HTTP exceptions
  if (!isExpectedError(exception)) {
  captureException(exception, {

packages/nestjs/test/sentry-global-filter.test.ts

@@ -8,6 +8,7 @@ import { SentryGlobalFilter } from '../src/setup';
 
 vi.mock('../src/helpers', () => ({
  isExpectedError: vi.fn(),
+ isWsOrRpcException: vi.fn(),
 }));
 
 vi.mock('@sentry/core', () => ({
@@ -27,6 +28,7 @@ describe('SentryGlobalFilter', () => {
  let mockLoggerError: any;
  let mockLoggerWarn: any;
  let isExpectedErrorMock: any;
+ let isWsOrRpcExceptionMock: any;
 
  beforeEach(() => {
  vi.clearAllMocks();
@@ -57,6 +59,7 @@ describe('SentryGlobalFilter', () => {
  mockCaptureException = vi.spyOn(SentryCore, 'captureException').mockReturnValue('mock-event-id');
 
  isExpectedErrorMock = vi.mocked(Helpers.isExpectedError).mockImplementation(() => false);
+ isWsOrRpcExceptionMock = vi.mocked(Helpers.isWsOrRpcException).mockImplementation(() => false);
  });
 
  describe('HTTP context', () => {
@@ -237,4 +240,86 @@ describe('SentryGlobalFilter', () => {
  expect(mockCaptureException).not.toHaveBeenCalled();
  });
  });
+
+ describe('WebSocket context', () => {
+ let mockEmit: ReturnType<typeof vi.fn>;
+
+ beforeEach(() => {
+ mockEmit = vi.fn();
+ vi.mocked(mockArgumentsHost.getType).mockReturnValue('ws');
+ vi.mocked(mockArgumentsHost.switchToWs).mockReturnValue({
+ getClient: () => ({ emit: mockEmit }),
+ getData: vi.fn(),
+ getPattern: vi.fn(),
+ });
+ });
+
+ it('captures unexpected errors and emits a generic error response', () => {
+ const error = new Error('Test WebSocket error');
+
+ filter.catch(error, mockArgumentsHost);
+
+ expect(mockCaptureException).toHaveBeenCalledWith(error, {
+ mechanism: {
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ },
+ });
+ expect(mockLoggerError).toHaveBeenCalledWith(error.message, error.stack);
+ expect(mockEmit).toHaveBeenCalledWith('exception', {
+ status: 'error',
+ message: 'Internal server error',
+ });
+ });
+
+ it('does not capture expected WebSocket exceptions and emits their response', () => {
+ isExpectedErrorMock.mockReturnValueOnce(true);
+ isWsOrRpcExceptionMock.mockReturnValueOnce(true);
+ const exception = {
+ getError: () => 'Expected WebSocket exception',
+ initMessage: vi.fn(),
+ };
+
+ filter.catch(exception, mockArgumentsHost);
+
+ expect(mockCaptureException).not.toHaveBeenCalled();
+ expect(mockEmit).toHaveBeenCalledWith('exception', {
+ status: 'error',
+ message: 'Expected WebSocket exception',
+ });
+ });
+
+ it('does not capture HTTP exceptions and emits a generic error response', () => {
+ isExpectedErrorMock.mockReturnValueOnce(true);
+ const exception = new HttpException('Bad request', HttpStatus.BAD_REQUEST);
+
+ filter.catch(exception, mockArgumentsHost);
+
+ expect(mockCaptureException).not.toHaveBeenCalled();
+ expect(mockLoggerError).toHaveBeenCalledWith(exception.message, exception.stack);
+ expect(mockEmit).toHaveBeenCalledWith('exception', {
+ status: 'error',
+ message: 'Internal server error',
+ });
+ });
+
+ it('captures unexpected errors when the WebSocket client cannot emit', () => {
+ vi.mocked(mockArgumentsHost.switchToWs).mockReturnValue({
+ getClient: () => ({}),
+ getData: vi.fn(),
+ getPattern: vi.fn(),
+ });
+ const error = new Error('WebSocket adapter without emit');
+
+ filter.catch(error, mockArgumentsHost);
+
+ expect(mockCaptureException).toHaveBeenCalledWith(error, {
+ mechanism: {
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ },
+ });
+ expect(mockLoggerError).toHaveBeenCalledWith(error.message, error.stack);
+ });
+ });
 });

dev-packages/e2e-tests/test-applications/nestjs-websockets/src/app.gateway.ts

@@ -1,13 +1,21 @@
-import { SubscribeMessage, WebSocketGateway, MessageBody } from '@nestjs/websockets';
+import { UseFilters } from '@nestjs/common';
+import { MessageBody, SubscribeMessage, WebSocketGateway, WsException } from '@nestjs/websockets';
 import * as Sentry from '@sentry/nestjs';
+import { SentryGlobalFilter } from '@sentry/nestjs/setup';
 
+@UseFilters(new SentryGlobalFilter())
 @WebSocketGateway()
 export class AppGateway {
  @SubscribeMessage('test-exception')
  handleTestException() {
  throw new Error('This is an exception in a WebSocket handler');
  }
 
+ @SubscribeMessage('test-ws-exception')
+ handleWsException() {
+ throw new WsException('Expected WebSocket exception');
+ }
+
  @SubscribeMessage('test-manual-capture')
  handleManualCapture() {
  try {

dev-packages/e2e-tests/test-applications/nestjs-websockets/tests/errors.test.ts

@@ -22,16 +22,39 @@ test('Captures manually reported error in WebSocket gateway handler', async ({ b
  socket.disconnect();
 });
 
+test('Automatically captures unexpected errors in WebSocket gateway handlers', async ({ baseURL }) => {
+ const errorPromise = waitForError('nestjs-websockets', event => {
+ return event.exception?.values?.[0]?.value === 'This is an exception in a WebSocket handler';
+ });
+
+ const socket = io(baseURL!);
+ await new Promise<void>(resolve => socket.on('connect', resolve));
+
+ socket.emit('test-exception', {});
+
+ const error = await errorPromise;
+
+ expect(error.exception?.values).toHaveLength(1);
+ expect(error.exception?.values?.[0]?.type).toBe('Error');
+ expect(error.exception?.values?.[0]?.value).toBe('This is an exception in a WebSocket handler');
+ expect(error.exception?.values?.[0]?.mechanism).toEqual({
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ });
+
+ socket.disconnect();
+});
+
 // There is no good mechanism to verify that an event was NOT sent to Sentry.
-// The idea here is that we first send a message that triggers an exception which won't be auto-captured,
+// The idea here is that we first send a message that triggers an expected exception which won't be auto-captured,
 // and then send a message that triggers a manually captured error which will be sent to Sentry.
 // If the manually captured error arrives, we can deduce that the first exception was not sent,
 // because Socket.IO guarantees message ordering: https://socket.io/docs/v4/delivery-guarantees
-test('Does not automatically capture exceptions in WebSocket gateway handler', async ({ baseURL }) => {
+test('Does not automatically capture expected WebSocket exceptions', async ({ baseURL }) => {
  let errorEventOccurred = false;
 
  waitForError('nestjs-websockets', event => {
- if (!event.type && event.exception?.values?.[0]?.value === 'This is an exception in a WebSocket handler') {
+ if (!event.type && event.exception?.values?.[0]?.value === 'Expected WebSocket exception') {
  errorEventOccurred = true;
  }
 
@@ -45,7 +68,7 @@ test('Does not automatically capture exceptions in WebSocket gateway handler', a
  const socket = io(baseURL!);
  await new Promise<void>(resolve => socket.on('connect', resolve));
 
- socket.emit('test-exception', {});
+ socket.emit('test-ws-exception', {});
  socket.emit('test-manual-capture', {});
  await manualCapturePromise;
 

packages/nestjs/src/helpers.ts

@@ -25,10 +25,24 @@ export function isExpectedError(exception: unknown): boolean {
  return true;
  }
 
- // RpcException
- if (typeof ex.getError === 'function' && typeof ex.initMessage === 'function') {
+ if (isWsOrRpcException(exception)) {
  return true;
  }
 
  return false;
 }
+
+/**
+ * Determines if the exception is a WsException or RpcException, which have the same shape.
+ * Both have `getError()` and `initMessage()` methods.
+ *
+ * We use duck-typing to avoid importing from `@nestjs/websockets` or `@nestjs/microservices`.
+ */
+export function isWsOrRpcException(exception: unknown): boolean {
+ if (typeof exception !== 'object' || exception === null) {
+ return false;
+ }
+
+ const ex = exception as Record<string, unknown>;
+ return typeof ex.getError === 'function' && typeof ex.initMessage === 'function';
+}

packages/nestjs/src/setup.ts

@@ -10,7 +10,7 @@ import { Catch, Global, HttpException, Injectable, Logger, Module } from '@nestj
 import { APP_INTERCEPTOR, BaseExceptionFilter } from '@nestjs/core';
 import { captureException, debug, getDefaultIsolationScope, getIsolationScope } from '@sentry/core';
 import type { Observable } from 'rxjs';
-import { isExpectedError } from './helpers';
+import { isExpectedError, isWsOrRpcException } from './helpers';
 
 // Partial extract of FastifyRequest interface
 // https://github.com/fastify/fastify/blob/87f9f20687c938828f1138f91682d568d2a31e53/types/request.d.ts#L41
@@ -152,6 +152,33 @@ class SentryGlobalFilter extends BaseExceptionFilter {
  return;
  }
 
+ if (contextType === 'ws') {
+ if (!isExpectedError(exception)) {
+ captureException(exception, {
+ mechanism: {
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ },
+ });
+ }
+
+ const client = host.switchToWs().getClient<{ emit?: (event: string, data: unknown) => void }>();
+
+ if (isWsOrRpcException(exception)) {
+ const result = (exception as { getError: () => unknown }).getError();
+ const response = typeof result === 'object' && result !== null ? result : { status: 'error', message: result };
+ client.emit?.('exception', response);
+ return;
+ }
+
+ if (exception instanceof Error) {
+ this._logger.error(exception.message, exception.stack);
+ }
+
+ client.emit?.('exception', { status: 'error', message: 'Internal server error' });
+ return;
+ }
+
  // HTTP exceptions
  if (!isExpectedError(exception)) {
  captureException(exception, {

packages/nestjs/test/sentry-global-filter.test.ts

@@ -8,6 +8,7 @@ import { SentryGlobalFilter } from '../src/setup';
 
 vi.mock('../src/helpers', () => ({
  isExpectedError: vi.fn(),
+ isWsOrRpcException: vi.fn(),
 }));
 
 vi.mock('@sentry/core', () => ({
@@ -27,6 +28,7 @@ describe('SentryGlobalFilter', () => {
  let mockLoggerError: any;
  let mockLoggerWarn: any;
  let isExpectedErrorMock: any;
+ let isWsOrRpcExceptionMock: any;
 
  beforeEach(() => {
  vi.clearAllMocks();
@@ -57,6 +59,7 @@ describe('SentryGlobalFilter', () => {
  mockCaptureException = vi.spyOn(SentryCore, 'captureException').mockReturnValue('mock-event-id');
 
  isExpectedErrorMock = vi.mocked(Helpers.isExpectedError).mockImplementation(() => false);
+ isWsOrRpcExceptionMock = vi.mocked(Helpers.isWsOrRpcException).mockImplementation(() => false);
  });
 
  describe('HTTP context', () => {
@@ -237,4 +240,86 @@ describe('SentryGlobalFilter', () => {
  expect(mockCaptureException).not.toHaveBeenCalled();
  });
  });
+
+ describe('WebSocket context', () => {
+ let mockEmit: ReturnType<typeof vi.fn>;
+
+ beforeEach(() => {
+ mockEmit = vi.fn();
+ vi.mocked(mockArgumentsHost.getType).mockReturnValue('ws');
+ vi.mocked(mockArgumentsHost.switchToWs).mockReturnValue({
+ getClient: () => ({ emit: mockEmit }),
+ getData: vi.fn(),
+ getPattern: vi.fn(),
+ });
+ });
+
+ it('captures unexpected errors and emits a generic error response', () => {
+ const error = new Error('Test WebSocket error');
+
+ filter.catch(error, mockArgumentsHost);
+
+ expect(mockCaptureException).toHaveBeenCalledWith(error, {
+ mechanism: {
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ },
+ });
+ expect(mockLoggerError).toHaveBeenCalledWith(error.message, error.stack);
+ expect(mockEmit).toHaveBeenCalledWith('exception', {
+ status: 'error',
+ message: 'Internal server error',
+ });
+ });
+
+ it('does not capture expected WebSocket exceptions and emits their response', () => {
+ isExpectedErrorMock.mockReturnValueOnce(true);
+ isWsOrRpcExceptionMock.mockReturnValueOnce(true);
+ const exception = {
+ getError: () => 'Expected WebSocket exception',
+ initMessage: vi.fn(),
+ };
+
+ filter.catch(exception, mockArgumentsHost);
+
+ expect(mockCaptureException).not.toHaveBeenCalled();
+ expect(mockEmit).toHaveBeenCalledWith('exception', {
+ status: 'error',
+ message: 'Expected WebSocket exception',
+ });
+ });
+
+ it('does not capture HTTP exceptions and emits a generic error response', () => {
+ isExpectedErrorMock.mockReturnValueOnce(true);
+ const exception = new HttpException('Bad request', HttpStatus.BAD_REQUEST);
+
+ filter.catch(exception, mockArgumentsHost);
+
+ expect(mockCaptureException).not.toHaveBeenCalled();
+ expect(mockLoggerError).toHaveBeenCalledWith(exception.message, exception.stack);
+ expect(mockEmit).toHaveBeenCalledWith('exception', {
+ status: 'error',
+ message: 'Internal server error',
+ });
+ });
+
+ it('captures unexpected errors when the WebSocket client cannot emit', () => {
+ vi.mocked(mockArgumentsHost.switchToWs).mockReturnValue({
+ getClient: () => ({}),
+ getData: vi.fn(),
+ getPattern: vi.fn(),
+ });
+ const error = new Error('WebSocket adapter without emit');
+
+ filter.catch(error, mockArgumentsHost);
+
+ expect(mockCaptureException).toHaveBeenCalledWith(error, {
+ mechanism: {
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ },
+ });
+ expect(mockLoggerError).toHaveBeenCalledWith(error.message, error.stack);
+ });
+ });
 });

dev-packages/e2e-tests/test-applications/nestjs-websockets/src/app.gateway.ts

@@ -1,13 +1,21 @@
-import { SubscribeMessage, WebSocketGateway, MessageBody } from '@nestjs/websockets';
+import { UseFilters } from '@nestjs/common';
+import { MessageBody, SubscribeMessage, WebSocketGateway, WsException } from '@nestjs/websockets';
 import * as Sentry from '@sentry/nestjs';
+import { SentryGlobalFilter } from '@sentry/nestjs/setup';
 
+@UseFilters(new SentryGlobalFilter())
 @WebSocketGateway()
 export class AppGateway {
  @SubscribeMessage('test-exception')
  handleTestException() {
  throw new Error('This is an exception in a WebSocket handler');
  }
 
+ @SubscribeMessage('test-ws-exception')
+ handleWsException() {
+ throw new WsException('Expected WebSocket exception');
+ }
+
  @SubscribeMessage('test-manual-capture')
  handleManualCapture() {
  try {

dev-packages/e2e-tests/test-applications/nestjs-websockets/tests/errors.test.ts

@@ -22,16 +22,39 @@ test('Captures manually reported error in WebSocket gateway handler', async ({ b
  socket.disconnect();
 });
 
+test('Automatically captures unexpected errors in WebSocket gateway handlers', async ({ baseURL }) => {
+ const errorPromise = waitForError('nestjs-websockets', event => {
+ return event.exception?.values?.[0]?.value === 'This is an exception in a WebSocket handler';
+ });
+
+ const socket = io(baseURL!);
+ await new Promise<void>(resolve => socket.on('connect', resolve));
+
+ socket.emit('test-exception', {});
+
+ const error = await errorPromise;
+
+ expect(error.exception?.values).toHaveLength(1);
+ expect(error.exception?.values?.[0]?.type).toBe('Error');
+ expect(error.exception?.values?.[0]?.value).toBe('This is an exception in a WebSocket handler');
+ expect(error.exception?.values?.[0]?.mechanism).toEqual({
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ });
+
+ socket.disconnect();
+});
+
 // There is no good mechanism to verify that an event was NOT sent to Sentry.
-// The idea here is that we first send a message that triggers an exception which won't be auto-captured,
+// The idea here is that we first send a message that triggers an expected exception which won't be auto-captured,
 // and then send a message that triggers a manually captured error which will be sent to Sentry.
 // If the manually captured error arrives, we can deduce that the first exception was not sent,
 // because Socket.IO guarantees message ordering: https://socket.io/docs/v4/delivery-guarantees
-test('Does not automatically capture exceptions in WebSocket gateway handler', async ({ baseURL }) => {
+test('Does not automatically capture expected WebSocket exceptions', async ({ baseURL }) => {
  let errorEventOccurred = false;
 
  waitForError('nestjs-websockets', event => {
- if (!event.type && event.exception?.values?.[0]?.value === 'This is an exception in a WebSocket handler') {
+ if (!event.type && event.exception?.values?.[0]?.value === 'Expected WebSocket exception') {
  errorEventOccurred = true;
  }
 
@@ -45,7 +68,7 @@ test('Does not automatically capture exceptions in WebSocket gateway handler', a
  const socket = io(baseURL!);
  await new Promise<void>(resolve => socket.on('connect', resolve));
 
- socket.emit('test-exception', {});
+ socket.emit('test-ws-exception', {});
  socket.emit('test-manual-capture', {});
  await manualCapturePromise;
 

packages/nestjs/src/helpers.ts

@@ -25,10 +25,24 @@ export function isExpectedError(exception: unknown): boolean {
  return true;
  }
 
- // RpcException
- if (typeof ex.getError === 'function' && typeof ex.initMessage === 'function') {
+ if (isWsOrRpcException(exception)) {
  return true;
  }
 
  return false;
 }
+
+/**
+ * Determines if the exception is a WsException or RpcException, which have the same shape.
+ * Both have `getError()` and `initMessage()` methods.
+ *
+ * We use duck-typing to avoid importing from `@nestjs/websockets` or `@nestjs/microservices`.
+ */
+export function isWsOrRpcException(exception: unknown): boolean {
+ if (typeof exception !== 'object' || exception === null) {
+ return false;
+ }
+
+ const ex = exception as Record<string, unknown>;
+ return typeof ex.getError === 'function' && typeof ex.initMessage === 'function';
+}

packages/nestjs/src/setup.ts

@@ -10,7 +10,7 @@ import { Catch, Global, HttpException, Injectable, Logger, Module } from '@nestj
 import { APP_INTERCEPTOR, BaseExceptionFilter } from '@nestjs/core';
 import { captureException, debug, getDefaultIsolationScope, getIsolationScope } from '@sentry/core';
 import type { Observable } from 'rxjs';
-import { isExpectedError } from './helpers';
+import { isExpectedError, isWsOrRpcException } from './helpers';
 
 // Partial extract of FastifyRequest interface
 // https://github.com/fastify/fastify/blob/87f9f20687c938828f1138f91682d568d2a31e53/types/request.d.ts#L41
@@ -152,6 +152,33 @@ class SentryGlobalFilter extends BaseExceptionFilter {
  return;
  }
 
+ if (contextType === 'ws') {
+ if (!isExpectedError(exception)) {
+ captureException(exception, {
+ mechanism: {
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ },
+ });
+ }
+
+ const client = host.switchToWs().getClient<{ emit?: (event: string, data: unknown) => void }>();
+
+ if (isWsOrRpcException(exception)) {
+ const result = (exception as { getError: () => unknown }).getError();
+ const response = typeof result === 'object' && result !== null ? result : { status: 'error', message: result };
+ client.emit?.('exception', response);
+ return;
+ }
+
+ if (exception instanceof Error) {
+ this._logger.error(exception.message, exception.stack);
+ }
+
+ client.emit?.('exception', { status: 'error', message: 'Internal server error' });
+ return;
+ }
+
  // HTTP exceptions
  if (!isExpectedError(exception)) {
  captureException(exception, {

packages/nestjs/test/sentry-global-filter.test.ts

@@ -8,6 +8,7 @@ import { SentryGlobalFilter } from '../src/setup';
 
 vi.mock('../src/helpers', () => ({
  isExpectedError: vi.fn(),
+ isWsOrRpcException: vi.fn(),
 }));
 
 vi.mock('@sentry/core', () => ({
@@ -27,6 +28,7 @@ describe('SentryGlobalFilter', () => {
  let mockLoggerError: any;
  let mockLoggerWarn: any;
  let isExpectedErrorMock: any;
+ let isWsOrRpcExceptionMock: any;
 
  beforeEach(() => {
  vi.clearAllMocks();
@@ -57,6 +59,7 @@ describe('SentryGlobalFilter', () => {
  mockCaptureException = vi.spyOn(SentryCore, 'captureException').mockReturnValue('mock-event-id');
 
  isExpectedErrorMock = vi.mocked(Helpers.isExpectedError).mockImplementation(() => false);
+ isWsOrRpcExceptionMock = vi.mocked(Helpers.isWsOrRpcException).mockImplementation(() => false);
  });
 
  describe('HTTP context', () => {
@@ -237,4 +240,86 @@ describe('SentryGlobalFilter', () => {
  expect(mockCaptureException).not.toHaveBeenCalled();
  });
  });
+
+ describe('WebSocket context', () => {
+ let mockEmit: ReturnType<typeof vi.fn>;
+
+ beforeEach(() => {
+ mockEmit = vi.fn();
+ vi.mocked(mockArgumentsHost.getType).mockReturnValue('ws');
+ vi.mocked(mockArgumentsHost.switchToWs).mockReturnValue({
+ getClient: () => ({ emit: mockEmit }),
+ getData: vi.fn(),
+ getPattern: vi.fn(),
+ });
+ });
+
+ it('captures unexpected errors and emits a generic error response', () => {
+ const error = new Error('Test WebSocket error');
+
+ filter.catch(error, mockArgumentsHost);
+
+ expect(mockCaptureException).toHaveBeenCalledWith(error, {
+ mechanism: {
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ },
+ });
+ expect(mockLoggerError).toHaveBeenCalledWith(error.message, error.stack);
+ expect(mockEmit).toHaveBeenCalledWith('exception', {
+ status: 'error',
+ message: 'Internal server error',
+ });
+ });
+
+ it('does not capture expected WebSocket exceptions and emits their response', () => {
+ isExpectedErrorMock.mockReturnValueOnce(true);
+ isWsOrRpcExceptionMock.mockReturnValueOnce(true);
+ const exception = {
+ getError: () => 'Expected WebSocket exception',
+ initMessage: vi.fn(),
+ };
+
+ filter.catch(exception, mockArgumentsHost);
+
+ expect(mockCaptureException).not.toHaveBeenCalled();
+ expect(mockEmit).toHaveBeenCalledWith('exception', {
+ status: 'error',
+ message: 'Expected WebSocket exception',
+ });
+ });
+
+ it('does not capture HTTP exceptions and emits a generic error response', () => {
+ isExpectedErrorMock.mockReturnValueOnce(true);
+ const exception = new HttpException('Bad request', HttpStatus.BAD_REQUEST);
+
+ filter.catch(exception, mockArgumentsHost);
+
+ expect(mockCaptureException).not.toHaveBeenCalled();
+ expect(mockLoggerError).toHaveBeenCalledWith(exception.message, exception.stack);
+ expect(mockEmit).toHaveBeenCalledWith('exception', {
+ status: 'error',
+ message: 'Internal server error',
+ });
+ });
+
+ it('captures unexpected errors when the WebSocket client cannot emit', () => {
+ vi.mocked(mockArgumentsHost.switchToWs).mockReturnValue({
+ getClient: () => ({}),
+ getData: vi.fn(),
+ getPattern: vi.fn(),
+ });
+ const error = new Error('WebSocket adapter without emit');
+
+ filter.catch(error, mockArgumentsHost);
+
+ expect(mockCaptureException).toHaveBeenCalledWith(error, {
+ mechanism: {
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ },
+ });
+ expect(mockLoggerError).toHaveBeenCalledWith(error.message, error.stack);
+ });
+ });
 });

dev-packages/e2e-tests/test-applications/nestjs-websockets/src/app.gateway.ts

@@ -1,13 +1,21 @@
-import { SubscribeMessage, WebSocketGateway, MessageBody } from '@nestjs/websockets';
+import { UseFilters } from '@nestjs/common';
+import { MessageBody, SubscribeMessage, WebSocketGateway, WsException } from '@nestjs/websockets';
 import * as Sentry from '@sentry/nestjs';
+import { SentryGlobalFilter } from '@sentry/nestjs/setup';
 
+@UseFilters(new SentryGlobalFilter())
 @WebSocketGateway()
 export class AppGateway {
  @SubscribeMessage('test-exception')
  handleTestException() {
  throw new Error('This is an exception in a WebSocket handler');
  }
 
+ @SubscribeMessage('test-ws-exception')
+ handleWsException() {
+ throw new WsException('Expected WebSocket exception');
+ }
+
  @SubscribeMessage('test-manual-capture')
  handleManualCapture() {
  try {

dev-packages/e2e-tests/test-applications/nestjs-websockets/tests/errors.test.ts

@@ -22,16 +22,39 @@ test('Captures manually reported error in WebSocket gateway handler', async ({ b
  socket.disconnect();
 });
 
+test('Automatically captures unexpected errors in WebSocket gateway handlers', async ({ baseURL }) => {
+ const errorPromise = waitForError('nestjs-websockets', event => {
+ return event.exception?.values?.[0]?.value === 'This is an exception in a WebSocket handler';
+ });
+
+ const socket = io(baseURL!);
+ await new Promise<void>(resolve => socket.on('connect', resolve));
+
+ socket.emit('test-exception', {});
+
+ const error = await errorPromise;
+
+ expect(error.exception?.values).toHaveLength(1);
+ expect(error.exception?.values?.[0]?.type).toBe('Error');
+ expect(error.exception?.values?.[0]?.value).toBe('This is an exception in a WebSocket handler');
+ expect(error.exception?.values?.[0]?.mechanism).toEqual({
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ });
+
+ socket.disconnect();
+});
+
 // There is no good mechanism to verify that an event was NOT sent to Sentry.
-// The idea here is that we first send a message that triggers an exception which won't be auto-captured,
+// The idea here is that we first send a message that triggers an expected exception which won't be auto-captured,
 // and then send a message that triggers a manually captured error which will be sent to Sentry.
 // If the manually captured error arrives, we can deduce that the first exception was not sent,
 // because Socket.IO guarantees message ordering: https://socket.io/docs/v4/delivery-guarantees
-test('Does not automatically capture exceptions in WebSocket gateway handler', async ({ baseURL }) => {
+test('Does not automatically capture expected WebSocket exceptions', async ({ baseURL }) => {
  let errorEventOccurred = false;
 
  waitForError('nestjs-websockets', event => {
- if (!event.type && event.exception?.values?.[0]?.value === 'This is an exception in a WebSocket handler') {
+ if (!event.type && event.exception?.values?.[0]?.value === 'Expected WebSocket exception') {
  errorEventOccurred = true;
  }
 
@@ -45,7 +68,7 @@ test('Does not automatically capture exceptions in WebSocket gateway handler', a
  const socket = io(baseURL!);
  await new Promise<void>(resolve => socket.on('connect', resolve));
 
- socket.emit('test-exception', {});
+ socket.emit('test-ws-exception', {});
  socket.emit('test-manual-capture', {});
  await manualCapturePromise;
 

packages/nestjs/src/helpers.ts

@@ -25,10 +25,24 @@ export function isExpectedError(exception: unknown): boolean {
  return true;
  }
 
- // RpcException
- if (typeof ex.getError === 'function' && typeof ex.initMessage === 'function') {
+ if (isWsOrRpcException(exception)) {
  return true;
  }
 
  return false;
 }
+
+/**
+ * Determines if the exception is a WsException or RpcException, which have the same shape.
+ * Both have `getError()` and `initMessage()` methods.
+ *
+ * We use duck-typing to avoid importing from `@nestjs/websockets` or `@nestjs/microservices`.
+ */
+export function isWsOrRpcException(exception: unknown): boolean {
+ if (typeof exception !== 'object' || exception === null) {
+ return false;
+ }
+
+ const ex = exception as Record<string, unknown>;
+ return typeof ex.getError === 'function' && typeof ex.initMessage === 'function';
+}

packages/nestjs/src/setup.ts

@@ -10,7 +10,7 @@ import { Catch, Global, HttpException, Injectable, Logger, Module } from '@nestj
 import { APP_INTERCEPTOR, BaseExceptionFilter } from '@nestjs/core';
 import { captureException, debug, getDefaultIsolationScope, getIsolationScope } from '@sentry/core';
 import type { Observable } from 'rxjs';
-import { isExpectedError } from './helpers';
+import { isExpectedError, isWsOrRpcException } from './helpers';
 
 // Partial extract of FastifyRequest interface
 // https://github.com/fastify/fastify/blob/87f9f20687c938828f1138f91682d568d2a31e53/types/request.d.ts#L41
@@ -152,6 +152,33 @@ class SentryGlobalFilter extends BaseExceptionFilter {
  return;
  }
 
+ if (contextType === 'ws') {
+ if (!isExpectedError(exception)) {
+ captureException(exception, {
+ mechanism: {
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ },
+ });
+ }
+
+ const client = host.switchToWs().getClient<{ emit?: (event: string, data: unknown) => void }>();
+
+ if (isWsOrRpcException(exception)) {
+ const result = (exception as { getError: () => unknown }).getError();
+ const response = typeof result === 'object' && result !== null ? result : { status: 'error', message: result };
+ client.emit?.('exception', response);
+ return;
+ }
+
+ if (exception instanceof Error) {
+ this._logger.error(exception.message, exception.stack);
+ }
+
+ client.emit?.('exception', { status: 'error', message: 'Internal server error' });
+ return;
+ }
+
  // HTTP exceptions
  if (!isExpectedError(exception)) {
  captureException(exception, {

packages/nestjs/test/sentry-global-filter.test.ts

@@ -8,6 +8,7 @@ import { SentryGlobalFilter } from '../src/setup';
 
 vi.mock('../src/helpers', () => ({
  isExpectedError: vi.fn(),
+ isWsOrRpcException: vi.fn(),
 }));
 
 vi.mock('@sentry/core', () => ({
@@ -27,6 +28,7 @@ describe('SentryGlobalFilter', () => {
  let mockLoggerError: any;
  let mockLoggerWarn: any;
  let isExpectedErrorMock: any;
+ let isWsOrRpcExceptionMock: any;
 
  beforeEach(() => {
  vi.clearAllMocks();
@@ -57,6 +59,7 @@ describe('SentryGlobalFilter', () => {
  mockCaptureException = vi.spyOn(SentryCore, 'captureException').mockReturnValue('mock-event-id');
 
  isExpectedErrorMock = vi.mocked(Helpers.isExpectedError).mockImplementation(() => false);
+ isWsOrRpcExceptionMock = vi.mocked(Helpers.isWsOrRpcException).mockImplementation(() => false);
  });
 
  describe('HTTP context', () => {
@@ -237,4 +240,86 @@ describe('SentryGlobalFilter', () => {
  expect(mockCaptureException).not.toHaveBeenCalled();
  });
  });
+
+ describe('WebSocket context', () => {
+ let mockEmit: ReturnType<typeof vi.fn>;
+
+ beforeEach(() => {
+ mockEmit = vi.fn();
+ vi.mocked(mockArgumentsHost.getType).mockReturnValue('ws');
+ vi.mocked(mockArgumentsHost.switchToWs).mockReturnValue({
+ getClient: () => ({ emit: mockEmit }),
+ getData: vi.fn(),
+ getPattern: vi.fn(),
+ });
+ });
+
+ it('captures unexpected errors and emits a generic error response', () => {
+ const error = new Error('Test WebSocket error');
+
+ filter.catch(error, mockArgumentsHost);
+
+ expect(mockCaptureException).toHaveBeenCalledWith(error, {
+ mechanism: {
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ },
+ });
+ expect(mockLoggerError).toHaveBeenCalledWith(error.message, error.stack);
+ expect(mockEmit).toHaveBeenCalledWith('exception', {
+ status: 'error',
+ message: 'Internal server error',
+ });
+ });
+
+ it('does not capture expected WebSocket exceptions and emits their response', () => {
+ isExpectedErrorMock.mockReturnValueOnce(true);
+ isWsOrRpcExceptionMock.mockReturnValueOnce(true);
+ const exception = {
+ getError: () => 'Expected WebSocket exception',
+ initMessage: vi.fn(),
+ };
+
+ filter.catch(exception, mockArgumentsHost);
+
+ expect(mockCaptureException).not.toHaveBeenCalled();
+ expect(mockEmit).toHaveBeenCalledWith('exception', {
+ status: 'error',
+ message: 'Expected WebSocket exception',
+ });
+ });
+
+ it('does not capture HTTP exceptions and emits a generic error response', () => {
+ isExpectedErrorMock.mockReturnValueOnce(true);
+ const exception = new HttpException('Bad request', HttpStatus.BAD_REQUEST);
+
+ filter.catch(exception, mockArgumentsHost);
+
+ expect(mockCaptureException).not.toHaveBeenCalled();
+ expect(mockLoggerError).toHaveBeenCalledWith(exception.message, exception.stack);
+ expect(mockEmit).toHaveBeenCalledWith('exception', {
+ status: 'error',
+ message: 'Internal server error',
+ });
+ });
+
+ it('captures unexpected errors when the WebSocket client cannot emit', () => {
+ vi.mocked(mockArgumentsHost.switchToWs).mockReturnValue({
+ getClient: () => ({}),
+ getData: vi.fn(),
+ getPattern: vi.fn(),
+ });
+ const error = new Error('WebSocket adapter without emit');
+
+ filter.catch(error, mockArgumentsHost);
+
+ expect(mockCaptureException).toHaveBeenCalledWith(error, {
+ mechanism: {
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ },
+ });
+ expect(mockLoggerError).toHaveBeenCalledWith(error.message, error.stack);
+ });
+ });
 });

dev-packages/e2e-tests/test-applications/nestjs-websockets/src/app.gateway.ts

@@ -1,13 +1,21 @@
-import { SubscribeMessage, WebSocketGateway, MessageBody } from '@nestjs/websockets';
+import { UseFilters } from '@nestjs/common';
+import { MessageBody, SubscribeMessage, WebSocketGateway, WsException } from '@nestjs/websockets';
 import * as Sentry from '@sentry/nestjs';
+import { SentryGlobalFilter } from '@sentry/nestjs/setup';
 
+@UseFilters(new SentryGlobalFilter())
 @WebSocketGateway()
 export class AppGateway {
  @SubscribeMessage('test-exception')
  handleTestException() {
  throw new Error('This is an exception in a WebSocket handler');
  }
 
+ @SubscribeMessage('test-ws-exception')
+ handleWsException() {
+ throw new WsException('Expected WebSocket exception');
+ }
+
  @SubscribeMessage('test-manual-capture')
  handleManualCapture() {
  try {

dev-packages/e2e-tests/test-applications/nestjs-websockets/tests/errors.test.ts

@@ -22,16 +22,39 @@ test('Captures manually reported error in WebSocket gateway handler', async ({ b
  socket.disconnect();
 });
 
+test('Automatically captures unexpected errors in WebSocket gateway handlers', async ({ baseURL }) => {
+ const errorPromise = waitForError('nestjs-websockets', event => {
+ return event.exception?.values?.[0]?.value === 'This is an exception in a WebSocket handler';
+ });
+
+ const socket = io(baseURL!);
+ await new Promise<void>(resolve => socket.on('connect', resolve));
+
+ socket.emit('test-exception', {});
+
+ const error = await errorPromise;
+
+ expect(error.exception?.values).toHaveLength(1);
+ expect(error.exception?.values?.[0]?.type).toBe('Error');
+ expect(error.exception?.values?.[0]?.value).toBe('This is an exception in a WebSocket handler');
+ expect(error.exception?.values?.[0]?.mechanism).toEqual({
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ });
+
+ socket.disconnect();
+});
+
 // There is no good mechanism to verify that an event was NOT sent to Sentry.
-// The idea here is that we first send a message that triggers an exception which won't be auto-captured,
+// The idea here is that we first send a message that triggers an expected exception which won't be auto-captured,
 // and then send a message that triggers a manually captured error which will be sent to Sentry.
 // If the manually captured error arrives, we can deduce that the first exception was not sent,
 // because Socket.IO guarantees message ordering: https://socket.io/docs/v4/delivery-guarantees
-test('Does not automatically capture exceptions in WebSocket gateway handler', async ({ baseURL }) => {
+test('Does not automatically capture expected WebSocket exceptions', async ({ baseURL }) => {
  let errorEventOccurred = false;
 
  waitForError('nestjs-websockets', event => {
- if (!event.type && event.exception?.values?.[0]?.value === 'This is an exception in a WebSocket handler') {
+ if (!event.type && event.exception?.values?.[0]?.value === 'Expected WebSocket exception') {
  errorEventOccurred = true;
  }
 
@@ -45,7 +68,7 @@ test('Does not automatically capture exceptions in WebSocket gateway handler', a
  const socket = io(baseURL!);
  await new Promise<void>(resolve => socket.on('connect', resolve));
 
- socket.emit('test-exception', {});
+ socket.emit('test-ws-exception', {});
  socket.emit('test-manual-capture', {});
  await manualCapturePromise;
 

packages/nestjs/src/helpers.ts

@@ -25,10 +25,24 @@ export function isExpectedError(exception: unknown): boolean {
  return true;
  }
 
- // RpcException
- if (typeof ex.getError === 'function' && typeof ex.initMessage === 'function') {
+ if (isWsOrRpcException(exception)) {
  return true;
  }
 
  return false;
 }
+
+/**
+ * Determines if the exception is a WsException or RpcException, which have the same shape.
+ * Both have `getError()` and `initMessage()` methods.
+ *
+ * We use duck-typing to avoid importing from `@nestjs/websockets` or `@nestjs/microservices`.
+ */
+export function isWsOrRpcException(exception: unknown): boolean {
+ if (typeof exception !== 'object' || exception === null) {
+ return false;
+ }
+
+ const ex = exception as Record<string, unknown>;
+ return typeof ex.getError === 'function' && typeof ex.initMessage === 'function';
+}

packages/nestjs/src/setup.ts

@@ -10,7 +10,7 @@ import { Catch, Global, HttpException, Injectable, Logger, Module } from '@nestj
 import { APP_INTERCEPTOR, BaseExceptionFilter } from '@nestjs/core';
 import { captureException, debug, getDefaultIsolationScope, getIsolationScope } from '@sentry/core';
 import type { Observable } from 'rxjs';
-import { isExpectedError } from './helpers';
+import { isExpectedError, isWsOrRpcException } from './helpers';
 
 // Partial extract of FastifyRequest interface
 // https://github.com/fastify/fastify/blob/87f9f20687c938828f1138f91682d568d2a31e53/types/request.d.ts#L41
@@ -152,6 +152,33 @@ class SentryGlobalFilter extends BaseExceptionFilter {
  return;
  }
 
+ if (contextType === 'ws') {
+ if (!isExpectedError(exception)) {
+ captureException(exception, {
+ mechanism: {
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ },
+ });
+ }
+
+ const client = host.switchToWs().getClient<{ emit?: (event: string, data: unknown) => void }>();
+
+ if (isWsOrRpcException(exception)) {
+ const result = (exception as { getError: () => unknown }).getError();
+ const response = typeof result === 'object' && result !== null ? result : { status: 'error', message: result };
+ client.emit?.('exception', response);
+ return;
+ }
+
+ if (exception instanceof Error) {
+ this._logger.error(exception.message, exception.stack);
+ }
+
+ client.emit?.('exception', { status: 'error', message: 'Internal server error' });
+ return;
+ }
+
  // HTTP exceptions
  if (!isExpectedError(exception)) {
  captureException(exception, {

packages/nestjs/test/sentry-global-filter.test.ts

@@ -8,6 +8,7 @@ import { SentryGlobalFilter } from '../src/setup';
 
 vi.mock('../src/helpers', () => ({
  isExpectedError: vi.fn(),
+ isWsOrRpcException: vi.fn(),
 }));
 
 vi.mock('@sentry/core', () => ({
@@ -27,6 +28,7 @@ describe('SentryGlobalFilter', () => {
  let mockLoggerError: any;
  let mockLoggerWarn: any;
  let isExpectedErrorMock: any;
+ let isWsOrRpcExceptionMock: any;
 
  beforeEach(() => {
  vi.clearAllMocks();
@@ -57,6 +59,7 @@ describe('SentryGlobalFilter', () => {
  mockCaptureException = vi.spyOn(SentryCore, 'captureException').mockReturnValue('mock-event-id');
 
  isExpectedErrorMock = vi.mocked(Helpers.isExpectedError).mockImplementation(() => false);
+ isWsOrRpcExceptionMock = vi.mocked(Helpers.isWsOrRpcException).mockImplementation(() => false);
  });
 
  describe('HTTP context', () => {
@@ -237,4 +240,86 @@ describe('SentryGlobalFilter', () => {
  expect(mockCaptureException).not.toHaveBeenCalled();
  });
  });
+
+ describe('WebSocket context', () => {
+ let mockEmit: ReturnType<typeof vi.fn>;
+
+ beforeEach(() => {
+ mockEmit = vi.fn();
+ vi.mocked(mockArgumentsHost.getType).mockReturnValue('ws');
+ vi.mocked(mockArgumentsHost.switchToWs).mockReturnValue({
+ getClient: () => ({ emit: mockEmit }),
+ getData: vi.fn(),
+ getPattern: vi.fn(),
+ });
+ });
+
+ it('captures unexpected errors and emits a generic error response', () => {
+ const error = new Error('Test WebSocket error');
+
+ filter.catch(error, mockArgumentsHost);
+
+ expect(mockCaptureException).toHaveBeenCalledWith(error, {
+ mechanism: {
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ },
+ });
+ expect(mockLoggerError).toHaveBeenCalledWith(error.message, error.stack);
+ expect(mockEmit).toHaveBeenCalledWith('exception', {
+ status: 'error',
+ message: 'Internal server error',
+ });
+ });
+
+ it('does not capture expected WebSocket exceptions and emits their response', () => {
+ isExpectedErrorMock.mockReturnValueOnce(true);
+ isWsOrRpcExceptionMock.mockReturnValueOnce(true);
+ const exception = {
+ getError: () => 'Expected WebSocket exception',
+ initMessage: vi.fn(),
+ };
+
+ filter.catch(exception, mockArgumentsHost);
+
+ expect(mockCaptureException).not.toHaveBeenCalled();
+ expect(mockEmit).toHaveBeenCalledWith('exception', {
+ status: 'error',
+ message: 'Expected WebSocket exception',
+ });
+ });
+
+ it('does not capture HTTP exceptions and emits a generic error response', () => {
+ isExpectedErrorMock.mockReturnValueOnce(true);
+ const exception = new HttpException('Bad request', HttpStatus.BAD_REQUEST);
+
+ filter.catch(exception, mockArgumentsHost);
+
+ expect(mockCaptureException).not.toHaveBeenCalled();
+ expect(mockLoggerError).toHaveBeenCalledWith(exception.message, exception.stack);
+ expect(mockEmit).toHaveBeenCalledWith('exception', {
+ status: 'error',
+ message: 'Internal server error',
+ });
+ });
+
+ it('captures unexpected errors when the WebSocket client cannot emit', () => {
+ vi.mocked(mockArgumentsHost.switchToWs).mockReturnValue({
+ getClient: () => ({}),
+ getData: vi.fn(),
+ getPattern: vi.fn(),
+ });
+ const error = new Error('WebSocket adapter without emit');
+
+ filter.catch(error, mockArgumentsHost);
+
+ expect(mockCaptureException).toHaveBeenCalledWith(error, {
+ mechanism: {
+ handled: false,
+ type: 'auto.ws.nestjs.global_filter',
+ },
+ });
+ expect(mockLoggerError).toHaveBeenCalledWith(error.message, error.stack);
+ });
+ });
 });