UseFilters

Kind: Function

Source: packages/common/decorators/core/exception-filters.decorator.ts

Part of: Common

Decorator that binds exception filters to the scope of the controller or method, depending on its context.

When @UseFilters is used at the controller level, the filter will be applied to every handler (method) in the controller.

When @UseFilters is used at the individual handler level, the filter will apply only to that specific method.

@UseFilters() binds one or more exception filters to a controller or individual route handler. Controller-scoped filters handle exceptions from every handler in that controller, while method-scoped filters apply only to the decorated endpoint. It integrates with NestJS exception handling by allowing custom error response logic to run when matching exceptions are thrown.

Signature

ts
function UseFilters(filters: (ExceptionFilter | Function)[])

Parameters

Diagram

mermaid
graph LR
  A[Incoming Request] --> B[Controller Handler]
  B -->|Throws exception| C{Filter scope}
  C -->|Method-level @UseFilters| D[Method Exception Filter]
  C -->|Controller-level @UseFilters| E[Controller Exception Filter]
  D --> F[Custom Error Response]
  E --> F

Usage

ts
import {
  Catch,
  Controller,
  ExceptionFilter,
  ArgumentsHost,
  HttpException,
  Get,
  UseFilters,
} from '@nestjs/common';

@Catch(HttpException)
class HttpErrorFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const response = host.switchToHttp().getResponse();
    const status = exception.getStatus();

    response.status(status).json({
      statusCode: status,
      message: exception.message,
      handledBy: 'HttpErrorFilter',
    });
  }
}

// Applies the filter to every route in this controller.
@Controller('users')
@UseFilters(HttpErrorFilter)
export class UsersController {
  @Get()
  findAll() {
    return [];
  }

  // A method-level filter can be used for endpoint-specific behavior.
  @Get('special')
  @UseFilters(HttpErrorFilter)
  findSpecialUsers() {
    return [];
  }
}

AI Coding Instructions

• Apply @UseFilters() at the controller level for shared exception handling across all controller routes.
• Apply it at the handler level when an endpoint needs specialized error formatting or handling behavior.
• Ensure filter classes implement ExceptionFilter and use @Catch() to define the exception types they handle.
• Pass filter classes or filter instances to @UseFilters(); prefer classes when NestJS dependency injection is required.
• Keep filters focused on translating exceptions into responses; avoid placing business logic inside exception filters.

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)

• ApplicationGateway — integration/websockets/src/app.gateway.ts:12