# ExternalExceptionFilterContext

**Kind:** Class

**Source:** [`packages/core/exceptions/external-exception-filter-context.ts`](https://github.com/nestjs/nest/blob/master/packages/core/exceptions/external-exception-filter-context.ts#L14)

**Part of:** [Core](subsystem-packages-core)

`ExternalExceptionFilterContext` builds exception handling contexts for externally invoked handlers, such as controllers or gateway endpoints. It resolves local and global exception filters, then creates an `ExternalExceptionsHandler` configured to apply them in the correct order.

**Extends:** `BaseExceptionFilterContext`

## Methods

| Method | Signature | Returns |
|---|---|---|
| `create` | `create(instance: Controller, callback: RouterProxyCallback, module: string, contextId: undefined, inquirerId: string)` | `ExternalExceptionsHandler` |
| `getGlobalMetadata` | `getGlobalMetadata(contextId: undefined, inquirerId: string)` | `T` |

## Where it refuses work

- `ExternalExceptionFilterContext` stops the work with an early return when `isEmpty(filters)`.
- `ExternalExceptionFilterContext` stops the work with an early return when `!this.config`.
- `ExternalExceptionFilterContext` stops the work with an early return when `contextId === STATIC_CONTEXT && !inquirerId`.

## Diagram

```mermaid
graph LR
  A[External Handler Callback] --> B[ExternalExceptionFilterContext]
  B --> C[Resolve Method and Class Filters]
  B --> D[Read Global Filter Metadata]
  C --> E[ExternalExceptionsHandler]
  D --> E
  E --> F[Handle Thrown Exceptions]
```

## Usage

```ts
import { ExternalExceptionFilterContext } from '@nestjs/core/exceptions/external-exception-filter-context';

// Typically created and used internally by the Nest runtime.
const exceptionFilterContext = new ExternalExceptionFilterContext(
  container,
  applicationConfig,
);

// Create an exception handler for a controller method.
const exceptionHandler = exceptionFilterContext.create(
  usersController,
  usersController.findOne,
  moduleRef,
);

// Inspect globally configured exception filters when needed.
const globalFilters = exceptionFilterContext.getGlobalMetadata();

// Use the generated handler when invoking the external callback.
try {
  await usersController.findOne('123');
} catch (error) {
  await exceptionHandler.next(error, host);
}
```

## AI Coding Instructions

- Use `create()` to generate a dedicated `ExternalExceptionsHandler` for each external callback context rather than reusing handlers across unrelated routes or handlers.
- Preserve filter ordering: the context resolves and reverses applicable filters so method-, class-, and global-level filters execute as expected.
- Use `getGlobalMetadata()` when extending filter resolution behavior; account for both static global filters and request-scoped global filters.
- Treat this class as framework infrastructure: application code should generally configure filters through Nest APIs such as `useGlobalFilters()` or `@UseFilters()`.

## How it works

`ExternalExceptionFilterContext` is an exception-filter context builder for externally created handlers. It extends `BaseExceptionFilterContext`, accepts a `NestContainer` and optional `ApplicationConfig`, and passes the container to its base class. [packages/core/exceptions/external-exception-filter-context.ts:14-20](packages/core/exceptions/external-exception-filter-context.ts#L14-L20)

## `create()`

`create(instance, callback, module, contextId?, inquirerId?)` stores `module` as the inherited `moduleContext`, creates an `ExternalExceptionsHandler`, resolves exception-filter metadata for the supplied controller instance and callback, and returns that handler. [packages/core/exceptions/external-exception-filter-context.ts:22-43](packages/core/exceptions/external-exception-filter-context.ts#L22-L43)

The resolved metadata combines global filters, controller-class filters, and callback-method filters in that order through `ContextCreator.createContext()`. [packages/core/helpers/context-creator.ts:16-40](packages/core/helpers/context-creator.ts#L16-L40) It reads class metadata from the instance prototype’s constructor and method metadata from the callback, using the `EXCEPTION_FILTERS_METADATA` key passed by `create()`. [packages/core/exceptions/external-exception-filter-context.ts:32-38](packages/core/exceptions/external-exception-filter-context.ts#L32-L38) [packages/core/helpers/context-creator.ts:43-52](packages/core/helpers/context-creator.ts#L43-L52)

Before assigning resolved filters to the handler, `create()` reverses their array. If the resolved array is empty, it returns the new handler without assigning custom filters. [packages/core/exceptions/external-exception-filter-context.ts:31-43](packages/core/exceptions/external-exception-filter-context.ts#L31-L43)

Inherited filter resolution accepts an object with a `catch` function or a class/function with a name; it discards other entries. For objects, it uses the object directly. For classes, it looks up an injectable in the stored module and gets its instance for the supplied context and inquirer IDs; missing module context, module, injectable, or instance causes that filter to be omitted. [packages/core/exceptions/base-exception-filter-context.ts:18-36](packages/core/exceptions/base-exception-filter-context.ts#L18-L36) [packages/core/exceptions/base-exception-filter-context.ts:39-71](packages/core/exceptions/base-exception-filter-context.ts#L39-L71)

Each retained filter becomes metadata containing its `catch` method bound to the filter instance and exception metatypes read from `FILTER_CATCH_EXCEPTIONS` metadata on its constructor; absent catch metadata becomes an empty metatype array. [packages/core/exceptions/base-exception-filter-context.ts:32-36](packages/core/exceptions/base-exception-filter-context.ts#L32-L36) [packages/core/exceptions/base-exception-filter-context.ts:73-77](packages/core/exceptions/base-exception-filter-context.ts#L73-L77)

## Global-filter lookup

`getGlobalMetadata(contextId?, inquirerId?)` returns an empty array when the context was constructed without an `ApplicationConfig`. [packages/core/exceptions/external-exception-filter-context.ts:46-52](packages/core/exceptions/external-exception-filter-context.ts#L46-L52)

With configuration, a static context with no inquirer ID returns `ApplicationConfig.getGlobalFilters()` directly. [packages/core/exceptions/external-exception-filter-context.ts:53-56](packages/core/exceptions/external-exception-filter-context.ts#L53-L56) For another context or any inquirer ID, it gets global request-filter wrappers, resolves each wrapper for that context and inquirer, drops falsy instance hosts, extracts their instances, and concatenates them after the static global filters. [packages/core/exceptions/external-exception-filter-context.ts:57-65](packages/core/exceptions/external-exception-filter-context.ts#L57-L65)

`ApplicationConfig` stores static global filters separately from global request-filter wrappers; its related add methods append entries to those arrays. [packages/core/application-config.ts:17-23](packages/core/application-config.ts#L17-L23) [packages/core/application-config.ts:64-74](packages/core/application-config.ts#L64-L74) [packages/core/application-config.ts:122-128](packages/core/application-config.ts#L122-L128)

## Resulting handler and externally created callbacks

The returned `ExternalExceptionsHandler` selects the first assigned filter whose metatype list is empty or contains a constructor matched by `exception instanceof`; it invokes that filter’s bound `catch` function. If no custom filter matches, it calls its inherited `catch`, which logs non-intrinsic `Error` instances and rethrows the exception. [packages/core/exceptions/external-exceptions-handler.ts:11-17](packages/core/exceptions/external-exceptions-handler.ts#L11-L17) [packages/core/exceptions/external-exceptions-handler.ts:26-36](packages/core/exceptions/external-exceptions-handler.ts#L26-L36) [packages/common/utils/select-exception-filter-metadata.util.ts:3-13](packages/common/utils/select-exception-filter-metadata.util.ts#L3-L13) [packages/core/exceptions/external-exception-filter.ts:6-15](packages/core/exceptions/external-exception-filter.ts#L6-L15)

`ExternalContextCreator` constructs this context from a container and its application configuration, calls `create()` while building an external callback, and—when filters are enabled—wraps the callback in `ExternalErrorProxy`. [packages/core/helpers/external-context-creator.ts:56-88](packages/core/helpers/external-context-creator.ts#L56-L88) [packages/core/helpers/external-context-creator.ts:128-134](packages/core/helpers/external-context-creator.ts#L128-L134) [packages/core/helpers/external-context-creator.ts:178-184](packages/core/helpers/external-context-creator.ts#L178-L184) That proxy catches errors from the target callback, creates an `ExecutionContextHost` from callback arguments, sets its context type, and passes the error and host to the handler’s `next()` method. [packages/core/helpers/external-proxy.ts:6-18](packages/core/helpers/external-proxy.ts#L6-L18)

## Validation, errors, and side effects

This class has no explicit argument validation and no explicit `throw` statement. Its visible state mutation is assigning `this.moduleContext` during `create()`. [packages/core/exceptions/external-exception-filter-context.ts:22-31](packages/core/exceptions/external-exception-filter-context.ts#L22-L31) It also allocates a new `ExternalExceptionsHandler` per `create()` call. [packages/core/exceptions/external-exception-filter-context.ts:29-32](packages/core/exceptions/external-exception-filter-context.ts#L29-L32)

The handler’s `setCustomFilters()` throws `InvalidExceptionFilterException` if called with a non-array value, although this context passes the array returned by `createContext()`. [packages/core/exceptions/external-exceptions-handler.ts:19-24](packages/core/exceptions/external-exceptions-handler.ts#L19-L24) [packages/core/helpers/context-creator.ts:28-40](packages/core/helpers/context-creator.ts#L28-L40)

## Relationships

- IMPORTS → `EXCEPTION_FILTERS_METADATA`
- IMPORTS → `Controller`
- IMPORTS → `ExceptionFilterMetadata`
- IMPORTS → `isEmpty`