Core Concepts

Error Handling

A guide to error handling in Raptor

Introduction

Errors thrown in middleware are picked up and added to the Context object, allowing you to catch and handle them in the catch callback. By default, the system automatically catches errors for you. If you wish to change this behaviour, you can implement the catch method (see below). As with standard middleware responses, content types and HTTP status codes are automatically assigned, but you can override them if needed. The following errors are currently available to import and throw from within the framework:

Available error types

You can create your own errors by implementing the Error interface.

Disable automatic error catching

If you prefer to manage errors manually, you can disable the automatic error catching feature by implementing the catch method (see example below) to check for errors and handle the responses accordingly.

import { type Context, Kernel, NotFound } from "@raptor/kernel";
 
const app = new Kernel();
 
// Simulate an application error.
app.use(() => {
  throw new NotFound();
});
 
// Catch our error and handle response.
app.catch((context: Context) => {
  const { error } = context;
 
  if (error instanceof NotFound) {
    return new Response("This page could not be found", {
      status: 404,
    });
  }
 
  return new Response(error.stack ?? error.message, {
    status: "status" in error ? error.status : 500,
  })
});
 
app.serve();

Not enough?

Check out the Error package which provides a pretty error interface that helps you debug your web application, with a stacked error handling system.

© 2026 Raptor