# ExceptionFilterMetadata

**Kind:** Interface

**Source:** [`packages/common/interfaces/exceptions/exception-filter-metadata.interface.ts`](https://github.com/nestjs/nest/blob/master/packages/common/interfaces/exceptions/exception-filter-metadata.interface.ts#L4)

**Part of:** [Common](subsystem-packages-common)

`ExceptionFilterMetadata` describes the runtime metadata Nest uses to associate an exception filter handler with the exception classes it can process. It stores the filter's `catch` function alongside the exception metatypes registered through decorators such as `@Catch()`.

## Properties

| Property | Type |
|---|---|
| `func` | `ExceptionFilter['catch']` |
| `exceptionMetatypes` | `Type<any>[]` |

## Diagram

```mermaid
graph LR
  A["@Catch(HttpException)"] --> B["ExceptionFilterMetadata"]
  C["Exception Filter instance"] --> D["func: filter.catch"]
  A --> E["exceptionMetatypes: Type&lt;any&gt;[]"]
  D --> B
  E --> B
  B --> F["Exceptions handler selects matching filter"]
```

## Usage

```ts
import { ArgumentsHost, Catch, ExceptionFilter, HttpException } from '@nestjs/common';
import { ExceptionFilterMetadata } from '@nestjs/common/interfaces/exceptions/exception-filter-metadata.interface';

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

    response.status(exception.getStatus()).json({
      message: exception.message,
    });
  }
}

const filter = new HttpExceptionFilter();

const metadata: ExceptionFilterMetadata = {
  func: filter.catch.bind(filter),
  exceptionMetatypes: [HttpException],
};
```

## AI Coding Instructions

- Keep `func` compatible with `ExceptionFilter['catch']`; bind it to the filter instance when invoking it outside Nest's normal filter context.
- Populate `exceptionMetatypes` with exception constructors, such as `HttpException` or custom error classes, not instantiated exceptions.
- Treat this interface as internal runtime metadata used by Nest's exception-handler resolution flow.
- Preserve the relationship between a filter's `catch` handler and its declared `@Catch()` exception types when extending exception-filter infrastructure.

## How it works

`ExceptionFilterMetadata` is an exported TypeScript interface for the two values needed to select and invoke an exception filter: a `catch` function and an array of exception constructor types. It declares no executable logic, validation, errors, or side effects itself. [exception-filter-metadata.interface.ts:4-7](packages/common/interfaces/exceptions/exception-filter-metadata.interface.ts#L4-L7)

- `func` has the type of `ExceptionFilter['catch']`. That method receives an exception and an `ArgumentsHost`, and may return any value. [exception-filter-metadata.interface.ts:5](packages/common/interfaces/exceptions/exception-filter-metadata.interface.ts#L5) [exception-filter.interface.ts:10-18](packages/common/interfaces/exceptions/exception-filter.interface.ts#L10-L18)
- `exceptionMetatypes` is an array of constructible function types (`Type<any>`); `Type<T>` extends `Function` and has a `new (...args)` signature. [exception-filter-metadata.interface.ts:6](packages/common/interfaces/exceptions/exception-filter-metadata.interface.ts#L6) [type.interface.ts:1-3](packages/common/interfaces/type.interface.ts#L1-L3)

Filter-context construction creates metadata objects by binding each filter instance’s `catch` method to that instance and reading its catch-type metadata through reflection. [base-exception-filter-context.ts:26-36](packages/core/exceptions/base-exception-filter-context.ts#L26-L36) The `@Catch()` decorator writes the supplied exception types under the metadata key that this reflection reads. [catch.decorator.ts:21-27](packages/common/decorators/core/catch.decorator.ts#L21-L27) A filter can be registered through `@UseFilters()` as a class or instance; that decorator accepts functions or objects whose `catch` member is a function, otherwise it can throw `InvalidDecoratorItemException`. [exception-filters.decorator.ts:29-30](packages/common/decorators/core/exception-filters.decorator.ts#L29-L30) [exception-filters.decorator.ts:40-60](packages/common/decorators/core/exception-filters.decorator.ts#L40-L60) [validate-each.util.ts:23-29](packages/common/utils/validate-each.util.ts#L23-L29)

When selecting metadata for an exception, `selectExceptionFilterMetadata()` returns the first entry whose `exceptionMetatypes` array is empty or contains a constructor for which the exception is an `instanceof`; it returns `undefined` when no entry matches. [select-exception-filter-metadata.util.ts:3-13](packages/common/utils/select-exception-filter-metadata.util.ts#L3-L13)

`ExceptionsHandler` stores an array of these objects, invokes the selected entry’s `func(exception, ctx)`, and reports whether a matching entry existed. If no custom filter matches, its `next()` method delegates to the base exception handler. [exceptions-handler.ts:9-17](packages/core/exceptions/exceptions-handler.ts#L9-L17) [exceptions-handler.ts:26-37](packages/core/exceptions/exceptions-handler.ts#L26-L37) Its `setCustomFilters()` method requires the supplied value to be an array and throws `InvalidExceptionFilterException` otherwise; it does not inspect the shape of each array entry in the shown code. [exceptions-handler.ts:19-24](packages/core/exceptions/exceptions-handler.ts#L19-L24)

## Used by

4 references from 4 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.

### Imported by (4)

- `ExceptionsHandler` — `packages/core/exceptions/exceptions-handler.ts`:9
- `ExternalExceptionFilterContext` — `packages/core/exceptions/external-exception-filter-context.ts`:14
- `ExternalExceptionsHandler` — `packages/core/exceptions/external-exceptions-handler.ts`:8
- `WsExceptionsHandler` — `packages/websockets/exceptions/ws-exceptions-handler.ts`:12