Exception filters in NestJS

This chapter follows Pipes and validation in NestJS.

Code anywhere in a Nest request, whether a guard, a pipe, a handler, or a service three calls deep, can stop the request by throwing. The exception travels up to the exceptions layer, where filters turn it into a response. Without any filter of your own, Nest’s built-in one already does something sensible. Custom filters exist for when you want a different error format, logging, or a translation from domain errors to HTTP status codes.

The built-in behavior

The default filter knows one class: HttpException. An instance of it, or of a subclass, becomes a response with its status code and message:

1
throw new NotFoundException(`Cat ${id} not found`);

1
{
2
  "message": "Cat 42 not found",
3
  "error": "Not Found",
4
  "statusCode": 404
5
}

Anything else, such as a TypeError or an error from the database driver, becomes a generic 500 with "message": "Internal server error". The original message is not sent, which keeps stack traces and SQL out of responses, and Nest logs the error to the console.

Built-in HTTP exceptions

@nestjs/common exports a subclass for each common status, so code reads by intent rather than by number:

Each takes an optional message (or an object, which replaces the whole response body) and an options object with cause and description. The cause is not sent to the client, but it is kept for logging, so the lower-level error is not lost:

1
try {
2
  return await this.repository.insert(cat);
3
} catch (error) {
4
  throw new ConflictException('A cat with this name already exists', { cause: error });
5
}

Custom exceptions

Domain code often should not know about HTTP. A plain error class keeps the service independent, and a filter maps it to a status later:

1
export class CatLimitReachedError extends Error {
2
  constructor(readonly ownerId: string, readonly limit: number) {
3
    super(`Owner ${ownerId} already has ${limit} cats`);
4
  }
5
}

When a status is part of the meaning anyway, extend HttpException or one of its subclasses instead. The default filter then handles it without any further code.

Writing a filter

A filter implements ExceptionFilter. @Catch() lists the exception types it handles, and catch() receives the exception and an ArgumentsHost, which gives access to the request and response.

1
import { ArgumentsHost, Catch, ExceptionFilter, HttpStatus } from '@nestjs/common';
2
import type { Response } from 'express';
3
import { CatLimitReachedError } from './cat-limit-reached.error';
4

5
@Catch(CatLimitReachedError)
6
export class CatLimitReachedFilter implements ExceptionFilter {
7
  catch(exception: CatLimitReachedError, host: ArgumentsHost) {
8
    const response = host.switchToHttp().getResponse<Response>();
9
    response.status(HttpStatus.UNPROCESSABLE_ENTITY).json({
10
      statusCode: HttpStatus.UNPROCESSABLE_ENTITY,
11
      error: 'CAT_LIMIT_REACHED',
12
      message: exception.message,
13
      limit: exception.limit,
14
    });
15
  }
16
}

Bind it with @UseFilters(CatLimitReachedFilter) on a controller or route, or globally. Filters resolve from the most specific level outward: route, then controller, then global. The first filter whose @Catch() matches handles the exception, and no other filter sees it.

A catch-all filter

@Catch() with no arguments catches everything. Registered globally, it gives every error in the app one JSON shape and one place to log. Using the HttpAdapterHost instead of the Express response keeps it working on Fastify too:

1
import { ArgumentsHost, Catch, ExceptionFilter, HttpException, HttpStatus, Logger } from '@nestjs/common';
2
import { HttpAdapterHost } from '@nestjs/core';
3

4
@Catch()
5
export class AllExceptionsFilter implements ExceptionFilter {
6
  private readonly logger = new Logger(AllExceptionsFilter.name);
7

8
  constructor(private readonly adapterHost: HttpAdapterHost) {}
9

10
  catch(exception: unknown, host: ArgumentsHost) {
11
    const { httpAdapter } = this.adapterHost;
12
    const ctx = host.switchToHttp();
13
    const status =
14
      exception instanceof HttpException ? exception.getStatus() : HttpStatus.INTERNAL_SERVER_ERROR;
15

16
    if (status >= 500) this.logger.error(exception);
17

18
    httpAdapter.reply(
19
      ctx.getResponse(),
20
      {
21
        statusCode: status,
22
        message: exception instanceof HttpException ? exception.message : 'Internal server error',
23
        path: httpAdapter.getRequestUrl(ctx.getRequest()),
24
        timestamp: new Date().toISOString(),
25
      },
26
      status,
27
    );
28
  }
29
}

1
import { APP_FILTER } from '@nestjs/core';
2

3
@Module({
4
  providers: [{ provide: APP_FILTER, useClass: AllExceptionsFilter }],
5
})
6
export class AppModule {}

Register specific filters such as CatLimitReachedFilter at the controller level, or as further global filters. When several global filters are registered, declare the catch-all first: Nest checks the most recently registered global filter first, so a catch-all registered last would shadow the specific ones. Keep the catch-all as the last resort, not as the place where every domain error is translated.

Next: Configuration in NestJS.