Not Found Handler

The Not Found Handler component provides a centralized and consistent way to handle unmatched routes.

Instead of allowing undefined routes to return inconsistent responses or default Express errors, this component ensures that all unknown endpoints respond with a standardized 404 Not Found error.

This component exists to:

• Catch all requests to undefined routes
• Return a predictable and structured 404 response
• Integrate seamlessly with Servercn error handling
• Improve API reliability and developer experience

Installation Guide

This component requires additional Servercn components.

1. Install Servercn components(Optional)

• API Error Handler:

pnpmnpmyarnbun

npx servercn-cli add error-handler

Documentation: API Error Handler

⚠️ If this dependency is not installed, the component will not function correctly.

2. Install this component

pnpmnpmyarnbun

npx servercn-cli add not-found-handler

This component requires the API Error Handler component to function correctly.

Basic Implementation

The Not Found Handler is a middleware that catches all unmatched routes and throws a standardized 404 error.

1. MVC Structure

import { Request, Response, NextFunction } from "express";
import { ApiError } from "../utils/api-error";
 
export const notFoundHandler = (
  req: Request,
  res: Response,
  next: NextFunction
) => {
  throw ApiError.notFound(`Route ${req.method} ${req.originalUrl} not found`);
};

2. Feature Structure

import { Request, Response, NextFunction } from "express";
import { ApiError } from "../errors/api-error";
 
export const notFoundHandler = (
  req: Request,
  res: Response,
  next: NextFunction
) => {
  throw ApiError.notFound(`Route ${req.method} ${req.originalUrl} not found`);
};

Usage Example

The Not Found Handler must be placed after all routes but before the error handler in your Express application.

1. MVC Structure

import express, { type Application } from "express";
import "dotenv-flow/config";
import { errorHandler } from "./middlewares/error-handler";
import { notFoundHandler } from "./middlewares/not-found-handler";
 
const app: Application = express();
 
app.use(express.json());
 
// routes here
// ...
 
// Not found handler (should be after routes)
app.use(notFoundHandler);
 
// Global error handler (should be last)
app.use(errorHandler);
 
export default app;

2. Feature Structure

import express, { type Application } from "express";
import "dotenv-flow/config";
import { errorHandler } from "./shared/middlewares/error-handler";
import { notFoundHandler } from "./shared/middlewares/not-found-handler";
 
const app: Application = express();
 
app.use(express.json());
 
// routes here
// ...
 
// Not found handler (should be after routes)
app.use(notFoundHandler);
 
// Global error handler (should be last)
app.use(errorHandler);
 
export default app;

Response Format

When a route is not found, the handler returns a standardized 404 response:

{
  "success": false,
  "message": "Route GET /api/v1/invalid-route not found",
  "statusCode": 404
}

The exact format depends on your ApiError and ApiResponse configuration.

How It Works

1. Route Matching: Express processes routes in the order they are defined
2. Catch-All: The Not Found Handler is placed after all defined routes
3. Error Throwing: When a request doesn't match any route, it reaches the Not Found Handler
4. Error Propagation: The handler throws an ApiError with a 404 status code
5. Error Handling: The global error handler catches the error and returns a standardized response

Best Practices

• Use ApiError.notFound() for consistency
• Always place the Not Found Handler after all route definitions
• Always place the Not Found Handler before the global error handler
• The handler will catch all HTTP methods (GET, POST, PUT, DELETE, etc.)
• Customize the error message to include the method and path for better debugging

Why This Component Matters

Without a dedicated not found handler:

• Undefined routes may return HTML error pages
• Error responses become inconsistent
• Debugging API issues becomes harder

This component ensures:

• All API endpoints return JSON
• Status codes are correct and explicit
• Errors are handled uniformly