Exception filters in NestJS - Deep Dive

Overview - Exception filters

What is it?

Exception filters in NestJS are special classes that catch and handle errors thrown during the execution of your application. They let you control how errors are processed and what response is sent back to the client. This helps keep your app stable and user-friendly by managing unexpected problems gracefully.

Why it matters

Without exception filters, errors would bubble up and cause the app to crash or send confusing messages to users. Exception filters solve this by catching errors early and formatting responses clearly. This improves user experience and helps developers debug issues faster, making apps more reliable and professional.

Where it fits

Before learning exception filters, you should understand basic NestJS controllers, services, and how errors are thrown in JavaScript/TypeScript. After mastering filters, you can explore advanced error handling, custom decorators, and global middleware to build robust applications.

Mental Model

Core Idea

Exception filters act like safety nets that catch errors in your app and decide how to respond to them.

Think of it like...

Imagine walking on a tightrope with a safety net below. If you slip (an error happens), the net catches you and helps you land safely instead of falling hard. Exception filters are that net for your app's errors.

┌───────────────┐
│  Controller   │
└──────┬────────┘
       │ throws error
       ▼
┌───────────────┐
│ Exception     │
│ Filter (Catches)│
└──────┬────────┘
       │ handles error
       ▼
┌───────────────┐
│  Response to  │
│    Client     │
└───────────────┘

Build-Up - 7 Steps

1

Foundation

What are Exception Filters

Concept: Introduce the basic idea of exception filters as error handlers in NestJS.

In NestJS, when something goes wrong inside a controller or service, an error is thrown. Exception filters are classes that catch these errors so you can decide what to do next. They help you send clear messages back to users instead of letting the app crash or show confusing errors.

Result

You understand that exception filters catch errors and control the response sent to users.

Understanding that errors can be caught and handled separately from business logic helps keep your app clean and user-friendly.

2

Foundation

Basic Exception Filter Structure

Concept: Learn how to create a simple exception filter class in NestJS.

An exception filter is a class that implements the 'ExceptionFilter' interface and has a 'catch' method. This method receives the error and the context (like request and response objects). Inside 'catch', you decide how to respond, for example, sending a JSON error message with a status code.

Result

You can write a basic filter that catches errors and sends a custom response.

Knowing the structure of filters lets you customize error handling instead of relying on default behavior.

3

Intermediate

Using Filters with Built-in Exceptions

🤔Before reading on: do you think built-in HTTP exceptions are handled automatically or need custom filters? Commit to your answer.

Concept: Explore how NestJS handles built-in HTTP exceptions and how filters can customize their responses.

NestJS has built-in exceptions like 'HttpException' that already send proper HTTP status codes and messages. You can write filters to catch these exceptions and modify the response format or add logging. This lets you keep consistent error responses across your app.

Result

You can customize how standard HTTP errors appear to clients using filters.

Understanding built-in exceptions helps you extend error handling without rewriting existing logic.

4

Intermediate

Applying Filters Globally and Locally

🤔Before reading on: do you think filters apply only to one controller or can be global? Commit to your answer.

Concept: Learn how to apply exception filters to specific controllers, routes, or globally across the app.

You can attach filters to a single controller or route using decorators, or apply them globally in the main app module. Global filters catch all errors in the app, while local filters only catch errors in their scope. This flexibility helps organize error handling cleanly.

Result

You know how to control the scope of filters for better error management.

Knowing filter scope lets you handle errors differently in parts of your app, improving maintainability.

5

Intermediate

Creating Custom Exception Classes

Concept: Understand how to define your own error types to use with filters.

You can create custom exception classes by extending 'HttpException' or the base 'Error' class. This lets you throw meaningful errors with specific messages and status codes. Filters can then catch these custom exceptions and respond accordingly.

Result

You can throw and handle your own error types for clearer app logic.

Custom exceptions improve communication between your app's parts and make error handling more precise.

6

Advanced

Exception Filters with Async Operations

🤔Before reading on: do you think exception filters catch errors from async code automatically? Commit to your answer.

Concept: Learn how filters work with asynchronous code and promises.

Errors thrown inside async functions or rejected promises can be caught by exception filters if properly awaited or returned. However, unhandled promise rejections outside NestJS context may not be caught. Using async/await and returning promises ensures filters catch errors as expected.

Result

You understand how to handle async errors with filters reliably.

Knowing async error flow prevents silent failures and ensures consistent error handling.

7

Expert

Internals of Exception Filter Execution

🤔Before reading on: do you think filters run before or after middleware and guards? Commit to your answer.

Concept: Dive into the NestJS request lifecycle and where filters fit in error handling.

When a request comes in, NestJS runs middleware, guards, interceptors, then controllers. If an error is thrown, filters catch it after guards and interceptors but before the response is sent. This order allows filters to handle errors from any part of the request pipeline. Multiple filters can be stacked, and the most specific filter runs first.

Result

You see how filters integrate into the full request lifecycle and error flow.

Understanding filter placement helps design better error handling strategies and avoid conflicts.

Under the Hood

NestJS uses a centralized exception handling layer that intercepts errors thrown during request processing. When an error occurs, NestJS checks for any matching exception filters in the current context (route, controller, or global). It then calls the filter's 'catch' method, passing the error and execution context. The filter formats the response and sends it back to the client, preventing the error from crashing the app or leaking sensitive info.

Why designed this way?

This design separates error handling from business logic, making code cleaner and more maintainable. It also allows flexible error responses depending on context. Alternatives like try-catch everywhere would clutter code and be hard to maintain. NestJS's filter system builds on Express's error middleware but adds structured, class-based handling aligned with its modular architecture.

┌───────────────┐
│  Incoming     │
│  Request      │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Middleware &  │
│ Guards        │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Controller /  │
│ Service Logic │
└──────┬────────┘
       │ throws error
       ▼
┌───────────────┐
│ Exception     │
│ Filters       │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Response Sent │
│ to Client     │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do exception filters catch errors thrown inside middleware? Commit to yes or no.

Common Belief: Exception filters catch all errors anywhere in the app, including middleware.

Reality: Exception filters only catch errors thrown inside controllers, services, or pipes, not inside middleware. Middleware errors must be handled separately.

Why it matters: Assuming filters catch middleware errors can lead to unhandled exceptions crashing the app or leaking sensitive info.

Quick: Do you think global filters override local filters or run alongside them? Commit to your answer.

Common Belief: Global exception filters override any local filters and are the only ones that run.

Reality: Local filters run first if present; global filters run only if no local filter handles the error.

Why it matters: Misunderstanding this can cause unexpected error responses and make debugging harder.

Quick: Do you think throwing an error inside an async callback always triggers exception filters? Commit to yes or no.

Common Belief: Any error thrown inside async callbacks is automatically caught by exception filters.

Reality: Errors in async callbacks not properly awaited or returned may bypass filters and cause unhandled promise rejections.

Why it matters: This can cause silent failures or crashes, making apps unreliable.

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

Common Belief: Exception filters can safely modify the original error object before sending a response.

Reality: Modifying the original error can cause side effects elsewhere; filters should create new response objects instead.

Why it matters: Changing errors can lead to confusing logs and bugs in other parts of the app.

Expert Zone

1

Exception filters can be combined with interceptors to add logging or transform error responses in layered ways.

2

Filters can access the full execution context, allowing different responses based on request type (HTTP, WebSocket, RPC).

3

Stacking multiple filters requires understanding their order of execution to avoid conflicts or missed errors.

When NOT to use

Exception filters are not suitable for handling errors in middleware or outside NestJS request lifecycle. For those cases, use Express error middleware or global process error handlers. Also, avoid using filters for business logic validation errors; use pipes or guards instead.

Production Patterns

In production, global filters often format all errors into a consistent JSON structure with logging. Custom filters handle specific error types like database or authentication errors. Filters are combined with monitoring tools to alert on critical failures.

Connections

Middleware

Related but distinct error handling layers

Understanding middleware error handling clarifies where exception filters apply and where separate handling is needed.

Try-Catch Blocks

Builds-on and abstracts try-catch error handling

Exception filters centralize what try-catch blocks scattered across code would do, improving maintainability.

Safety Nets in Circus Acts

Conceptual parallel in risk management

Knowing how safety nets catch falls in real life helps appreciate how filters catch errors to keep apps safe.

Common Pitfalls

#1 Assuming filters catch errors thrown in middleware

Wrong approach:

throw new Error('Middleware error'); // expecting exception filter to catch

Correct approach:

Use Express error middleware:
app.use((err, req, res, next) => { res.status(500).send('Error handled'); });

Root cause:

Misunderstanding the scope of exception filters versus middleware error handling.

#2 Not applying filters globally when needed

Wrong approach:

@UseFilters(MyFilter) // only on one controller, missing global errors

Correct approach:

app.useGlobalFilters(new MyFilter()); // applies filter app-wide

Root cause:

Not realizing filters can be scoped globally or locally, leading to inconsistent error handling.

#3 Throwing errors inside async callbacks without await

Wrong approach:

setTimeout(() => { throw new Error('Async error'); }, 1000);

Correct approach:

await new Promise((_, reject) => setTimeout(() => reject(new Error('Async error')), 1000));

Root cause:

Not handling async errors properly so filters can catch them.

Key Takeaways

Exception filters in NestJS catch errors thrown in controllers and services to control error responses.

Filters can be applied locally to controllers or globally to the whole app for flexible error handling.

They work well with built-in and custom exceptions, improving app reliability and user experience.

Filters only catch errors within NestJS lifecycle, so middleware errors need separate handling.

Understanding filter execution order and async error flow is key to building robust applications.