Global exception filters in NestJS

Introduction

Global exception filters help catch and handle errors in one place for your whole NestJS app. This keeps your code clean and consistent.

You want to send the same error response format for all errors in your app.

You need to log all exceptions in a central place.

You want to handle unexpected errors gracefully without crashing the app.

You want to customize HTTP error responses globally.

You want to avoid repeating error handling code in every controller.

Syntax

NestJS

import { ExceptionFilter, Catch, ArgumentsHost, HttpException } from '@nestjs/common';
import { Request, Response } from 'express';

@Catch()
export class AllExceptionsFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();
    const request = ctx.getRequest<Request>();

    const status = exception instanceof HttpException
      ? exception.getStatus()
      : 500;

    response.status(status).json({
      statusCode: status,
      timestamp: new Date().toISOString(),
      path: request.url,
      message: exception instanceof HttpException ? exception.getResponse() : 'Internal server error',
    });
  }
}

// To apply globally in main.ts
// app.useGlobalFilters(new AllExceptionsFilter());

The @Catch() decorator without arguments catches all exceptions.

Use app.useGlobalFilters() in your main bootstrap file to apply the filter globally.

Examples

This filter catches only HTTP exceptions, not all errors.

NestJS

import { ExceptionFilter, Catch, ArgumentsHost, HttpException } from '@nestjs/common';

@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    // handle only HttpException errors
  }
}

This line applies your custom exception filter to the whole app globally.

NestJS

app.useGlobalFilters(new AllExceptionsFilter());

Sample Program

This example shows a global exception filter catching all errors. The '/error' route throws a known HTTP error, '/unknown-error' throws a normal error, and '/hello' returns a normal response. The filter sends JSON error responses for exceptions.

NestJS

import { NestFactory } from '@nestjs/core';
import { Module, Controller, Get } from '@nestjs/common';
import { ExceptionFilter, Catch, ArgumentsHost, HttpException } from '@nestjs/common';
import { Request, Response } from 'express';

@Catch()
class AllExceptionsFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();
    const request = ctx.getRequest<Request>();

    const status = exception instanceof HttpException
      ? exception.getStatus()
      : 500;

    response.status(status).json({
      statusCode: status,
      timestamp: new Date().toISOString(),
      path: request.url,
      message: exception instanceof HttpException ? exception.getResponse() : 'Internal server error',
    });
  }
}

@Controller()
class AppController {
  @Get('error')
  throwError() {
    throw new HttpException('Custom error message', 400);
  }

  @Get('unknown-error')
  throwUnknownError() {
    throw new Error('Unknown error');
  }

  @Get('hello')
  hello() {
    return 'Hello World!';
  }
}

@Module({
  controllers: [AppController],
})
class AppModule {}

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalFilters(new AllExceptionsFilter());
  await app.listen(3000);
}

bootstrap();

Important Notes

Global filters catch exceptions from all controllers and services.

Always return consistent error response shapes for better client handling.

Use instanceof HttpException to check if the error is a known HTTP error.

Summary

Global exception filters catch errors app-wide in one place.

They help send consistent error responses and improve app stability.

Apply them in main.ts using app.useGlobalFilters().

Practice

1. What is the main purpose of a global exception filter in a NestJS application?

easy

A. To catch and handle exceptions across the entire application in one place

B. To define routes for the application

C. To manage database connections

D. To serve static files

Solution

1. Step 1: Understand the role of exception filters

   Exception filters in NestJS are designed to catch errors and exceptions that occur during request processing.

2. Step 2: Identify the scope of global exception filters

   Global exception filters apply this error handling across the entire app, centralizing error management.

3. Final Answer:

   To catch and handle exceptions across the entire application in one place -> Option A

4. Quick Check:

   Global exception filters = app-wide error handling [OK]

Hint: Global filters catch errors everywhere in the app [OK]

Common Mistakes:

• Confusing filters with routing or database management
• Thinking filters serve static files
• Assuming filters only handle specific routes

2. Which of the following is the correct way to apply a global exception filter in the main.ts file of a NestJS app?

easy

A. app.useGlobalFilters(new MyExceptionFilter())

B. app.setGlobalFilters(new MyExceptionFilter())

C. app.applyGlobalFilters(MyExceptionFilter)

D. app.registerGlobalFilter(MyExceptionFilter)

Solution

1. Step 1: Recall the NestJS method for global filters

   The official method to apply global exception filters is useGlobalFilters() on the app instance.

2. Step 2: Check the syntax for passing the filter

   The filter must be instantiated with new before passing it to useGlobalFilters().

3. Final Answer:

   app.useGlobalFilters(new MyExceptionFilter()) -> Option A

4. Quick Check:

   Global filter method = useGlobalFilters() [OK]

Hint: Use app.useGlobalFilters(new Filter()) in main.ts [OK]

Common Mistakes:

• Using incorrect method names like setGlobalFilters
• Passing class without instantiation
• Confusing with middleware registration methods

3. Given this global exception filter code snippet, what will be the HTTP status code returned when an exception is thrown?

import { ExceptionFilter, Catch, ArgumentsHost, HttpException } from '@nestjs/common';

@Catch()
export class AllExceptionsFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse();

    if (exception instanceof HttpException) {
      const status = exception.getStatus();
      response.status(status).json({ message: exception.message });
    } else {
      response.status(500).json({ message: 'Internal server error' });
    }
  }
}

medium

A. 200

B. 500

C. Depends on the exception type

D. 404

Solution

1. Step 1: Analyze the filter's catch method

   The filter checks if the exception is an instance of HttpException and uses its status code.

2. Step 2: Determine status code for other exceptions

   If not an HttpException, it returns status 500 with a generic error message.

3. Final Answer:

   Depends on the exception type -> Option C

4. Quick Check:

   HttpException status or 500 for others [OK]

Hint: Check if exception is HttpException for status code [OK]

Common Mistakes:

• Assuming always 500 status
• Ignoring HttpException status extraction
• Confusing 404 with 500 errors

4. Identify the error in this global exception filter implementation:

import { ExceptionFilter, Catch, ArgumentsHost } from '@nestjs/common';

@Catch()
export class MyFilter implements ExceptionFilter {
  catch(exception: any, host: ArgumentsHost) {
    const response = host.getResponse();
    response.status(400).json({ error: 'Bad Request' });
  }
}

medium

A. Missing @Injectable() decorator on the filter class

B. The @Catch() decorator must specify exception types

C. The catch method must return a value

D. host.getResponse() is incorrect; should use host.switchToHttp().getResponse()

Solution

1. Step 1: Check how to get response object

   In NestJS, to get the HTTP response, use host.switchToHttp().getResponse(), not host.getResponse().

2. Step 2: Verify other parts

   The @Catch() decorator can be empty to catch all exceptions, and the catch method does not need to return a value. @Injectable() is not required for filters.

3. Final Answer:

   host.getResponse() is incorrect; should use host.switchToHttp().getResponse() -> Option D

4. Quick Check:

   Use switchToHttp() to access response [OK]

Hint: Use host.switchToHttp().getResponse() to get response [OK]

Common Mistakes:

• Calling host.getResponse() directly
• Thinking @Injectable() is mandatory for filters
• Expecting catch to return a value

5. You want to create a global exception filter that logs all exceptions and returns a JSON response with a custom message and status code 418 (I'm a teapot) for all errors except HttpExceptions, which should keep their original status. How should you implement the catch method?

hard

A. Always respond with status 418 and ignore HttpException status

B. Check if exception is HttpException, use its status; else log and respond with 418 and custom message

C. Only log exceptions but do not modify the response

D. Throw the exception again to let NestJS handle it

Solution

1. Step 1: Handle HttpException separately

   Check if the exception is an instance of HttpException to preserve its status and message.

2. Step 2: For other exceptions, log and respond with status 418

   Log the error details, then send a JSON response with status 418 and a custom message.

3. Final Answer:

   Check if exception is HttpException, use its status; else log and respond with 418 and custom message -> Option B

4. Quick Check:

   Preserve HttpException status, else respond 418 with log [OK]

Hint: Preserve HttpException status; else respond 418 with log [OK]

Common Mistakes:

• Ignoring HttpException status and always sending 418
• Not logging exceptions
• Re-throwing exceptions instead of handling