Lifecycle

Request lifecycle

A request can be intercepted and terminated (with or without a response) from any of these layers, in this order:

import { definePlugin } from "nitro";

export default definePlugin((nitroApp) => {
  nitroApp.hooks.hook("request", (event) => {
    console.log(`Incoming request on ${event.req.url}`);
  });
});

import { defineConfig } from "nitro";

export default defineConfig({
  routeRules: {
    '/**': { headers: { 'x-nitro': 'first' } }
  }
})

import { defineHandler } from "nitro";

export default defineHandler((event) => {
  event.context.info = { name: "Nitro" };
});

export default (event) => ({ world: true })

import { defineHandler } from "nitro";

export default defineHandler((event) => {
  if (event.url.pathname === "/") {
    return "Home page";
  }
});

import { definePlugin } from "nitro";

export default definePlugin((nitroApp) => {
  nitroApp.hooks.hook("response", (res, event) => {
    console.log(`Response ${res.status} for ${event.req.url}`);
  });
});

Error handling

When an error occurs at any point in the request lifecycle, Nitro:

Throwing errors

Throw an HTTPError from any handler or middleware to end the request with a specific status code, message, and optional data:

import { defineHandler, HTTPError } from "nitro";

export default defineHandler((event) => {
  // Message and details
  throw new HTTPError("Invalid user input", { status: 400 });

  // Status code shortcut
  throw HTTPError.status(400, "Bad Request");

  // Full object form
  throw new HTTPError({
    status: 400,
    message: "Invalid user input",
    data: { field: "email" },
  });
});

Default error responses

In production, the default error handler always responds with JSON:

{
  "error": true,
  "status": 400,
  "message": "Invalid user input",
  "data": { "field": "email" }
}

In development, programmatic requests receive the same JSON format, but when the request's Accept header includes text/html (browsers), Nitro renders an interactive HTML error page with a source-mapped stack trace.

Custom error handlers

To control error response formatting, set errorHandler in the Nitro config to a file that exports a handler with defineErrorHandler:

import { defineConfig } from "nitro";

export default defineConfig({
  errorHandler: "~/error",
});

import { defineErrorHandler } from "nitro";

export default defineErrorHandler((error, event) => {
  return new Response(`[custom error] ${error.message}`, {
    status: error.status || 500,
    headers: { "Content-Type": "text/plain" },
  });
});

Return a Response to send it to the client, or return nothing to fall through to the next handler. errorHandler also accepts an array of handlers that run in order — the first one that returns a response wins, and the built-in default handler is always appended as the last entry, so there is always a fallback response:

import { defineConfig } from "nitro";

export default defineConfig({
  errorHandler: ["~/error/known-errors", "~/error/fallback"],
});

If a handler itself throws, the failure is logged and the chain continues with the next handler. Each handler also receives the built-in defaultHandler as { defaultHandler } in its third argument, so you can reuse the default rendering within your own logic.

To customize error rendering for the development server only (without affecting the production bundle), pass a handler function as devErrorHandler:

import { defineConfig } from "nitro";
import errorHandler from "./error.ts";

export default defineConfig({
  devErrorHandler: errorHandler,
});

Observing errors

To observe errors without changing the response, use the error runtime hook from a plugin:

import { definePlugin } from "nitro";

export default definePlugin((nitroApp) => {
  nitroApp.hooks.hook("error", (error, context) => {
    console.error("Captured error:", error);
    // context.event - the H3 event (if available)
    // context.tags  - error source tags like "request", "response", "plugin"
  });
});

You can also feed errors into the same pipeline programmatically with nitroApp.captureError. Errors are also tracked per-request in event.req.context.nitro.errors for inspection in later hooks.

Additionally, unhandled promise rejections and uncaught exceptions at the process level are automatically captured into the error hook with the tags "unhandledRejection" and "uncaughtException".

Server shutdown

When the Nitro server is shutting down, the close hook is called. Use this to clean up resources such as database connections, timers, or external service handles:

import { definePlugin } from "nitro";

export default definePlugin((nitroApp) => {
  nitroApp.hooks.hook("close", async () => {
    // Clean up resources
  });
});

Hooks reference

All runtime hooks are registered through runtime plugins using nitroApp.hooks.hook().