{"id":"a788ad03806fd5aa","repo":"nestjs/nest","slug":"invalid-exception-filters-usefilters","errorCode":null,"errorMessage":"Invalid exception filters (@UseFilters()).","messagePattern":"Invalid exception filters \\(@UseFilters\\(\\)\\)\\.","errorType":"exception","errorClass":"InvalidExceptionFilterException","httpStatus":null,"severity":"error","filePath":"packages/microservices/exceptions/rpc-exceptions-handler.ts","lineNumber":29,"sourceCode":" * @publicApi\n */\nexport class RpcExceptionsHandler extends BaseRpcExceptionFilter {\n  private filters: RpcExceptionFilterMetadata[] = [];\n\n  public handle(\n    exception: Error | RpcException,\n    host: ArgumentsHost,\n  ): Observable<any> {\n    const filterResult$ = this.invokeCustomFilters(exception, host);\n    if (filterResult$) {\n      return filterResult$;\n    }\n    return super.catch(exception, host);\n  }\n\n  public setCustomFilters(filters: RpcExceptionFilterMetadata[]) {\n    if (!Array.isArray(filters)) {\n      throw new InvalidExceptionFilterException();\n    }\n    this.filters = filters;\n  }\n\n  public invokeCustomFilters<T = any>(\n    exception: T,\n    host: ArgumentsHost,\n  ): Observable<any> | null {\n    if (isEmpty(this.filters)) {\n      return null;\n    }\n\n    const filter = selectExceptionFilterMetadata(this.filters, exception);\n    return filter ? filter.func(exception, host) : null;\n  }\n}\n","sourceCodeStart":11,"sourceCodeEnd":46,"githubUrl":"https://github.com/nestjs/nest/blob/6ec0e2783d15290732447f304d8549b591b9749e/packages/microservices/exceptions/rpc-exceptions-handler.ts#L11-L46","documentation":"Thrown as InvalidExceptionFilterException ('Invalid exception filters (@UseFilters()).') from RpcExceptionsHandler.setCustomFilters() when the filters argument is not an Array. The RPC exception handler expects the @UseFilters() metadata to resolve to an array of filter instances/classes; if a single non-array value (or undefined) is passed in, registration is rejected before any exception is handled.","triggerScenarios":"Applying @UseFilters() with no arguments, or with a malformed argument, that resolves to a non-array when NestJS collects filter metadata. Programmatically calling handler.setCustomFilters(someFilter) with a single filter instead of [someFilter]. Custom decorator that mangles the UseFilters metadata into a non-array.","commonSituations":"@UseFilters() written with empty parentheses and an accidental non-array payload from a custom decorator. Misuse of the internal RpcExceptionsHandler via custom adapters. Framework version mismatch where UseFilters metadata shape changed and a third-party plugin still emits the old shape.","solutions":["Pass filter classes/instances as an array literal to @UseFilters(): @UseFilters(RpcExceptionFilter) or @UseFilters([FilterA, FilterB]).","If calling setCustomFilters directly, pass an array: handler.setCustomFilters([myFilter]).","Audit custom decorators wrapping @UseFilters to ensure they forward an array of filters.","Update third-party exception-filter plugins to the NestJS version you are running."],"exampleFix":"// before\n@UseFilters() // empty or malformed\n@MessagePattern('getUser')\nget() {...}\n\n// after\n@UseFilters(new RpcExceptionFilter())\n@MessagePattern('getUser')\nget() {...}","handlingStrategy":"validation","validationCode":"function normalizeFilters(filters: unknown): any[] {\n  if (filters == null) return [];\n  return Array.isArray(filters) ? filters : [filters];\n}\n// Pass the normalized array to @UseFilters / setCustomFilters.","typeGuard":"const isInvalidFiltersError = (e: unknown): boolean =>\n  /Invalid exception filters/.test((e as Error)?.message ?? '');","tryCatchPattern":"// This throws during filter registration (startup), not per-request.\n// Ensure @UseFilters receives filter classes/instances (or an array of them).","preventionTips":["Always pass concrete filter classes/instances to @UseFilters, never undefined.","If calling setCustomFilters directly, pass an array.","Audit custom decorators that wrap @UseFilters to forward arrays."],"tags":["exception-filters","use-filters","rpc","nestjs","typescript"],"analyzedSha":"6ec0e2783d15290732447f304d8549b591b9749e","analyzedAt":"2026-08-03T17:42:23.673Z","schemaVersion":2}