# UseFilters

**Kind:** Function

**Source:** [`packages/common/decorators/core/exception-filters.decorator.ts`](https://github.com/nestjs/nest/blob/master/packages/common/decorators/core/exception-filters.decorator.ts#L29)

**Part of:** [Common](subsystem-packages-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

| Name | Type |
|---|---|
| `filters` | `(ExceptionFilter | Function)[]` |

## 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