Global exception filters in NestJS - Deep Dive

Overview - Global exception filters

What is it?

Global exception filters in NestJS are special pieces of code that catch and handle errors happening anywhere in your application. They let you control how errors are processed and what response is sent back to the user. Instead of handling errors in every part of your app, you write one global filter to manage them all. This makes your app cleaner and easier to maintain.

Why it matters

Without global exception filters, every part of your app would need its own error handling, leading to repeated code and inconsistent responses. This can confuse users and make debugging harder. Global filters solve this by centralizing error handling, improving user experience and developer productivity. They help keep your app stable and predictable even when unexpected problems happen.

Where it fits

Before learning global exception filters, you should understand basic NestJS concepts like controllers, providers, and middleware. After mastering global filters, you can explore advanced error handling techniques like custom exceptions, interceptors, and logging integrations. This topic fits into the error management and application robustness part of your NestJS learning journey.

Mental Model

Core Idea

A global exception filter is a single catcher that handles all errors thrown anywhere in your NestJS app, shaping consistent responses and logging.

Think of it like...

Imagine a safety net under a tightrope walker that catches any fall no matter where it happens, preventing injury and allowing a smooth show.

┌─────────────────────────────┐
│       NestJS Application    │
│ ┌───────────────┐           │
│ │ Controllers   │           │
│ │ & Services    │           │
│ └──────┬────────┘           │
│        │ Throws errors       │
│        ▼                    │
│ ┌─────────────────────────┐ │
│ │ Global Exception Filter │ │
│ │  Catches all errors     │ │
│ │  Sends uniform response │ │
│ └─────────────────────────┘ │
└─────────────────────────────┘

Build-Up - 6 Steps

1

Foundation

What is an Exception Filter

Concept: Learn what exception filters are and their role in NestJS error handling.

In NestJS, an exception filter is a class that implements a method to catch errors thrown during request processing. It decides how to respond to the client when something goes wrong. Filters can be applied to specific routes or globally to cover the whole app.

Result

You understand that exception filters catch errors and control responses in NestJS.

Knowing that filters centralize error handling helps you avoid scattering error code everywhere.

2

Foundation

Creating a Basic Exception Filter

Concept: How to write a simple exception filter class in NestJS.

You create a class that implements the ExceptionFilter interface and defines a catch() method. This method receives the error and the context of the request. Inside catch(), you can log the error and send a custom response using the response object.

Result

You can write a filter that catches errors and sends a simple JSON error message.

Understanding the catch() method parameters is key to customizing error responses.

3

Intermediate

Applying Filters Globally

🤔Before reading on: do you think global filters catch errors from all controllers automatically or only from those explicitly linked? Commit to your answer.

Concept: Learn how to register an exception filter so it handles errors across the entire NestJS app.

NestJS lets you apply filters globally by using app.useGlobalFilters() in the main bootstrap function. This means any error thrown anywhere in the app will be caught by this filter without needing to add it to each controller or route.

Result

Your filter now catches all errors in the app, ensuring consistent error handling everywhere.

Knowing global registration simplifies maintenance and guarantees uniform error responses.

4

Intermediate

Handling Different Error Types

🤔Before reading on: do you think a global filter treats all errors the same or can it respond differently based on error type? Commit to your answer.

Concept: Filters can check error types to customize responses for different exceptions.

Inside catch(), you can check if the error is an instance of HttpException or a custom error class. Based on this, you can set different HTTP status codes and messages. This allows your filter to handle validation errors, not found errors, or unexpected errors differently.

Result

Your global filter sends tailored responses depending on the error type, improving client feedback.

Understanding error type checking lets you build smarter, user-friendly error handling.

5

Advanced

Integrating Logging and Monitoring

🤔Before reading on: do you think global filters can also help with logging errors automatically? Commit to your answer.

Concept: Global filters can be extended to log errors or send them to monitoring services.

You can inject a logging service into your filter and call it inside catch() to record error details. This helps track issues in production. You can also integrate with tools like Sentry or Datadog by sending error info from the filter.

Result

Your app automatically logs all errors caught globally, aiding debugging and monitoring.

Knowing filters can handle logging centralizes error tracking and reduces duplicated code.

6

Expert

Performance and Error Propagation Considerations

🤔Before reading on: do you think global filters can affect app performance or error flow? Commit to your answer.

Concept: Understand how global filters impact app performance and how errors propagate after being caught.

Global filters add a small overhead because they run on every error. However, they prevent unhandled exceptions from crashing the app. Also, once an error is caught by a global filter, it stops propagating further. This means filters must be carefully designed to not swallow errors silently or block other error handlers.

Result

You appreciate the tradeoffs of global filters and design them to balance performance and error transparency.

Understanding error flow control prevents bugs where errors disappear or cause unexpected app behavior.

Under the Hood

When an error is thrown during a request, NestJS looks for any registered exception filters. If a global filter is registered, NestJS calls its catch() method with the error and request context. The filter then decides how to respond, often by setting HTTP status and sending a JSON message. This happens inside the framework's request lifecycle, ensuring errors don't crash the server but are handled gracefully.

Why designed this way?

NestJS designed global filters to centralize error handling for consistency and maintainability. Before this, developers had to handle errors in many places, leading to duplicated code and inconsistent responses. The filter system is flexible, allowing both global and scoped filters, balancing control and convenience.

┌───────────────┐
│ Request comes │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Controller /  │
│ Service Logic │
└──────┬────────┘
       │ Throws error
       ▼
┌─────────────────────────────┐
│ NestJS Exception Handling    │
│ ┌─────────────────────────┐ │
│ │ Global Exception Filter │ │
│ │  catch(error, context)  │ │
│ └─────────────────────────┘ │
└──────────────┬──────────────┘
               │
               ▼
       Sends HTTP response
       with error details

Myth Busters - 4 Common Misconceptions

Quick: Do global exception filters catch errors thrown inside asynchronous code automatically? Commit to yes or no.

Common Belief: Global exception filters catch every error in the app, including those inside async callbacks or promises.

Reality: Global filters catch errors thrown synchronously or rejected promises returned by route handlers, but errors inside async callbacks or event listeners may not be caught automatically.

Why it matters: Assuming all async errors are caught can lead to unhandled promise rejections or crashes, causing app instability.

Quick: Do you think you can have multiple global exception filters active at the same time? Commit to yes or no.

Common Belief: You can register many global exception filters and they will all run in order on every error.

Reality: NestJS allows only one global exception filter instance; registering multiple replaces the previous one.

Why it matters: Trying to stack global filters without knowing this can cause unexpected behavior or lost error handling logic.

Quick: Does a global exception filter automatically log errors to the console? Commit to yes or no.

Common Belief: Global exception filters log all errors by default without extra code.

Reality: Filters only do what you program them to do; logging must be explicitly added inside the catch() method.

Why it matters: Assuming automatic logging can cause missed error reports and harder debugging.

Quick: Do you think global exception filters can modify the original error object? Commit to yes or no.

Common Belief: Global filters should never change the error object to keep error integrity.

Reality: Filters can modify or wrap errors to customize responses, but this must be done carefully to avoid hiding important info.

Why it matters: Misunderstanding this can lead to either leaking sensitive info or losing critical debugging details.

Expert Zone

1

Global filters run after any scoped filters, so their order affects which errors they catch and how responses are shaped.

2

Filters can be combined with interceptors to add pre- and post-processing around error handling, enabling advanced workflows.

3

Using dependency injection inside filters allows integrating complex services like distributed tracing or feature flags for error responses.

When NOT to use

Global exception filters are not ideal when you need very different error handling logic per module or route; in those cases, scoped filters or middleware are better. Also, for non-HTTP contexts like microservices, other error handling patterns may be preferred.

Production Patterns

In production, global filters often include structured logging, error masking to hide sensitive info, and integration with monitoring tools. Teams also use filters to enforce consistent API error formats and to trigger alerts on critical failures.

Connections

Middleware

Both middleware and global exception filters can intercept requests, but middleware runs before controllers while filters handle errors after they occur.

Understanding middleware helps grasp the request lifecycle stages where filters operate, clarifying error flow.

Circuit Breaker Pattern

Global exception filters can work with circuit breakers by catching errors from failing services and responding gracefully.

Knowing how filters integrate with resilience patterns improves app stability under failure conditions.

Air Traffic Control Systems

Like global exception filters managing all errors centrally, air traffic control monitors and handles all flight issues to keep the system safe.

Seeing error handling as centralized control helps appreciate the importance of global filters in complex systems.

Common Pitfalls

#1 Not registering the global filter properly, so it never catches errors.

Wrong approach:

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

Correct approach:

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

Root cause:

Missing the call to app.useGlobalFilters means the filter is created but not applied globally.

#2 Catching errors but not sending any response, causing requests to hang.

Wrong approach:

catch(exception: any, host: ArgumentsHost) {
console.error(exception);
// No response sent
}

Correct approach:

catch(exception: any, host: ArgumentsHost) {
const ctx = host.switchToHttp();
const response = ctx.getResponse();
response.status(500).json({ message: 'Internal server error' });
}

Root cause:

Not sending a response leaves the client waiting indefinitely, causing timeouts.

#3 Swallowing errors silently without logging or rethrowing.

Wrong approach:

catch(exception: any, host: ArgumentsHost) {
// Empty catch block
}

Correct approach:

catch(exception: any, host: ArgumentsHost) {
console.error(exception);
const ctx = host.switchToHttp();
const response = ctx.getResponse();
response.status(500).json({ message: 'Error occurred' });
}

Root cause:

Ignoring errors hides problems and makes debugging impossible.

Key Takeaways

Global exception filters in NestJS centralize error handling, making your app more consistent and maintainable.

They catch errors thrown anywhere in the app and let you customize the HTTP response sent to clients.

Registering filters globally ensures all errors are handled uniformly without repeating code in controllers.

Filters can check error types to tailor responses and integrate logging or monitoring for production readiness.

Understanding how filters fit in the request lifecycle helps avoid common pitfalls like unhandled async errors or silent failures.

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