Error Handlers

Catch and format uncaught exceptions with global and group-level error handlers.

Error handlers in Nooh let you intercept unhandled exceptions and transform them into structured, predictable HTTP responses.

Global Error Handler

Define a global error handler in your nooh.config.ts file using the onError option:

import { config } from "@nooh-ts/nooh";
import { HTTPException } from "hono/http-exception";
import { UserNotFoundError } from "./src/errors/user";

export default config({
  routes: "src/routes",

  onError: (error, c) => {
    // 1. Handle HTTP Exceptions
    if (error instanceof HTTPException) {
      return c.json(
        {
          error: {
            code: "HTTP_EXCEPTION",
            message: error.message,
          },
        },
        error.status
      );
    }

    // 2. Handle Custom Domain Errors
    if (error instanceof UserNotFoundError) {
      return c.json(
        {
          error: {
            code: error.code,
            message: error.message,
            userId: error.userId,
          },
        },
        404
      );
    }

    // 3. Fallback for unexpected errors (500 Internal Server Error)
    console.error("Unhandled server error:", error);
    return c.json(
      {
        error: {
          code: "INTERNAL_SERVER_ERROR",
          message: "An unexpected error occurred.",
        },
      },
      500
    );
  },
});

Endpoint-Level Error Handlers

You can also attach an onError handler directly to an individual route endpoint options object:

import { get } from "@router/users/[id]";

export default get({
  handler: async ({ c }) => {
    // ...
  },
  onError: (error, c) => {
    return c.json({ customError: error.message }, 400);
  },
});

Route Group Error Handlers

You can scope error handling to specific sub-paths or route groups by declaring an onError handler in the group’s group.ts file:

import { group } from "@nooh-ts/nooh";

export default group({
  onError: (error, c) => {
    // This handler will only catch errors thrown within /api/v1/*
    return c.json(
      {
        apiVersion: "1.0",
        error: error.message,
      },
      500
    );
  },
});

Error Handler Signature

The NoohErrorHandler type matches Hono’s ErrorHandler signature:

import type { Context, Env } from "hono";
import type { HandlerResponse, HTTPResponseError } from "hono/types";

export type NoohErrorHandler<
  Environment extends Env = Env,
  Path extends string = string,
> = (
  error: Error | HTTPResponseError,
  c: Context<Environment, Path>
) => HandlerResponse<unknown>;

This guarantees full compatibility with existing Hono middleware and plugins.