Exception handling in NestJS v10 is implemented through exception filters.
Throwing Standard Exceptions
NestJS provides standard exception classes, such as HttpException, for throwing HTTP exceptions.
// src/exceptions/standard.exception.ts
import { HttpException, HttpStatus } from '@nestjs/common';
export class StandardException extends HttpException {
constructor(message: string) {
super(message, HttpStatus.BAD_REQUEST);
}
}Custom Exceptions
You can create custom exception classes to handle specific error scenarios.
// src/exceptions/custom.exception.ts
import { HttpException, HttpStatus } from '@nestjs/common';
export class CustomException extends HttpException {
constructor(public readonly code: number, message: string) {
super({ error: message, code }, HttpStatus.BAD_REQUEST);
}
}Built-in HTTP Exceptions
NestJS provides a range of built-in HTTP exception classes, such as BadRequestException, NotFoundException, and others.
// src/controllers/users.controller.ts
import { Controller, Get, Param } from '@nestjs/common';
import { UsersService } from './users.service';
import { NotFoundException } from '@nestjs/common';
@Controller('users')
export class UsersController {
constructor(private readonly usersService: UsersService) {}
@Get(':id')
async findOne(@Param('id') id: string) {
const user = await this.usersService.findOne(+id);
if (!user) {
throw new NotFoundException(`User #${id} not found`);
}
return user;
}
}Exception Filters
Exception filters capture and handle exceptions, allowing you to return a standardized error response.
// src/filters/http-exception.filter.ts
import { ExceptionFilter, Catch, ArgumentsHost, HttpException, HttpStatus } from '@nestjs/common';
import { Request, Response } from 'express';
@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
catch(exception: HttpException, host: ArgumentsHost) {
const ctx = host.switchToHttp();
const response = ctx.getResponse<Response>();
const request = ctx.getRequest<Request>();
const status = exception.getStatus();
const errorResponse = {
statusCode: status,
timestamp: new Date().toISOString(),
path: request.url,
message: exception.message,
};
response.status(status).json(errorResponse);
}
}Arguments Host
The ArgumentsHost interface is used to access contextual information during exception handling.
// src/filters/http-exception.filter.ts
import { ExceptionFilter, Catch, ArgumentsHost, HttpException, HttpStatus } from '@nestjs/common';
import { Request, Response } from 'express';
@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
catch(exception: HttpException, host: ArgumentsHost) {
const ctx = host.switchToHttp();
const response = ctx.getResponse<Response>();
const request = ctx.getRequest<Request>();
const status = exception.getStatus();
const errorResponse = {
statusCode: status,
timestamp: new Date().toISOString(),
path: request.url,
message: exception.message,
};
response.status(status).json(errorResponse);
}
}Binding Filters
Exception filters must be bound in a module to take effect.
// src/app.module.ts
import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { HttpExceptionFilter } from './filters/http-exception.filter';
@Module({
imports: [],
controllers: [AppController],
providers: [AppService, HttpExceptionFilter],
})
export class AppModule {}Catch All
You can create a global exception filter to capture all exceptions.
// src/filters/all-exceptions.filter.ts
import { ExceptionFilter, Catch, ArgumentsHost, HttpException, HttpStatus } 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() : HttpStatus.INTERNAL_SERVER_ERROR;
const errorResponse = {
statusCode: status,
timestamp: new Date().toISOString(),
path: request.url,
message: exception instanceof HttpException ? exception.message : 'Internal server error',
};
response.status(status).json(errorResponse);
}
}Inheritance
You can inherit from existing exception classes to create more specific exceptions.
// src/exceptions/user-not-found.exception.ts
import { NotFoundException } from '@nestjs/common';
export class UserNotFoundException extends NotFoundException {
constructor(id: number) {
super(`User #${id} not found`);
}
}Custom Exception
// src/exceptions/custom.exception.ts
import { HttpException, HttpStatus } from '@nestjs/common';
export class CustomException extends HttpException {
constructor(public readonly code: number, message: string) {
super({ error: message, code }, HttpStatus.BAD_REQUEST);
}
}Exception Filter
// src/filters/http-exception.filter.ts
import { ExceptionFilter, Catch, ArgumentsHost, HttpException, HttpStatus } from '@nestjs/common';
import { Request, Response } from 'express';
@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
catch(exception: HttpException, host: ArgumentsHost) {
const ctx = host.switchToHttp();
const response = ctx.getResponse<Response>();
const request = ctx.getRequest<Request>();
const status = exception.getStatus();
const errorResponse = {
statusCode: status,
timestamp: new Date().toISOString(),
path: request.url,
message: exception.message,
};
response.status(status).json(errorResponse);
}
}Controller
// src/controllers/users.controller.ts
import { Controller, Get, Param } from '@nestjs/common';
import { UsersService } from './users.service';
import { NotFoundException } from '@nestjs/common';
import { UserNotFoundException } from '../exceptions/user-not-found.exception';
@Controller('users')
export class UsersController {
constructor(private readonly usersService: UsersService) {}
@Get(':id')
async findOne(@Param('id') id: string) {
const user = await this.usersService.findOne(+id);
if (!user) {
throw new UserNotFoundException(+id);
}
return user;
}
}Main Module
// src/app.module.ts
import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { HttpExceptionFilter } from './filters/http-exception.filter';
@Module({
imports: [],
controllers: [AppController],
providers: [AppService, HttpExceptionFilter],
})
export class AppModule {}
