Fastify HTTP Errors Enhanced Plugin

7.0.1 · active · verified Wed Apr 22

This plugin for Fastify integrates `http-errors-enhanced` to provide comprehensive and customizable error handling for web applications. It allows developers to configure how 404 errors are handled, whether unhandled server errors expose stack traces in production, and how validation errors (both request and response) are structured. The current stable version is 7.0.1. Releases appear to follow major version bumps for Node.js compatibility changes and minor/patch releases for bug fixes and dependency updates, indicating an active and well-maintained project with a steady, predictable cadence. A key differentiator is its ability to convert validation errors into a structured, human-readable format and its extensibility for modifying error processing or customizing AJV instances for response validation. It provides a consistent error response format compatible with standard Fastify errors, capable of including custom properties and headers derived from the enhanced error objects.

Common errors

```
Error: fastify-http-errors-enhanced requires Node.js version >= 22.21.0
```
cause The installed Node.js version is older than the minimum requirement for the current `fastify-http-errors-enhanced` version.

fix Upgrade your Node.js environment to at least version 22.21.0, or downgrade `fastify-http-errors-enhanced` to a major version compatible with your current Node.js version.
```
TypeError: server.addHook is not a function
```
cause This error typically occurs if you try to register a Fastify plugin after routes have been defined, or if Fastify's plugin registration order is incorrect for hooks like `onRoute`.

fix Ensure `fastify-http-errors-enhanced` is registered early in your Fastify application setup, preferably before any routes are defined, and use `await server.register(...)` to ensure proper asynchronous registration.

Warnings

breaking `fastify-http-errors-enhanced` v7.0.0 and later drops compatibility with Node.js 20. Ensure your environment meets the minimum Node.js version specified in the `engines` field (currently `>= 22.21.0`).
Fix: Upgrade your Node.js environment to version 22.21.0 or higher, or use a previous major version of `fastify-http-errors-enhanced` that supports your Node.js version.
breaking Version 6.0.0 of `fastify-http-errors-enhanced` dropped support for Node.js 18. If you are using Node.js 18, you must remain on a version prior to 6.0.0.
Fix: Upgrade your Node.js environment to version 20 or higher, or pin `fastify-http-errors-enhanced` to a version like `^5.0.0` if you need Node.js 18 compatibility.
gotcha Due to the plugin's use of an `onRoute` hook, you must either `await server.register(plugin)` or wrap your route definitions within another plugin. Synchronous route definitions without awaiting can lead to unexpected error handling behavior.
Fix: Always use `await server.register(fastifyHttpErrorsEnhanced)` when setting up your Fastify instance, or encapsulate routes that rely on this plugin within a `fastify-plugin` block.
gotcha The `hideUnhandledErrors` and `convertResponsesValidationErrors` options default to different behaviors based on the `NODE_ENV` environment variable. In `production`, `hideUnhandledErrors` is `true`, and `convertResponsesValidationErrors` is `false` by default. Be explicit if you need different behavior.
Fix: Explicitly set `hideUnhandledErrors: true/false` and `convertResponsesValidationErrors: true/false` in the plugin options when registering to ensure consistent behavior across environments regardless of `NODE_ENV`.

Install

npm install fastify-http-errors-enhanced npm
yarn add fastify-http-errors-enhanced yarn
pnpm add fastify-http-errors-enhanced pnpm

Imports

fastifyHttpErrorsEnhanced

wrong:

const fastifyHttpErrorsEnhanced = require('fastify-http-errors-enhanced')

correct:

import fastifyHttpErrorsEnhanced from 'fastify-http-errors-enhanced'

The package is ESM-only and should be imported using `import` statements.

NotFoundError
wrong:
```
import { NotFoundError } from 'fastify-http-errors-enhanced'
```
correct:
```
import { NotFoundError } from 'http-errors-enhanced'
```
Error classes like NotFoundError are re-exported from `http-errors-enhanced`, not the plugin itself.
FastifyHttpErrorsEnhancedOptions
```
import type { FastifyHttpErrorsEnhancedOptions } from 'fastify-http-errors-enhanced'
```
This type can be imported for configuring the plugin options with TypeScript.

Quickstart

This quickstart demonstrates how to register the `fastify-http-errors-enhanced` plugin, configure its options, and throw an enhanced `NotFoundError` within a route handler to see the custom error response format and headers in action. It also shows a basic working route.

import fastify from 'fastify'
import fastifyHttpErrorsEnhanced from 'fastify-http-errors-enhanced'
import { NotFoundError } from 'http-errors-enhanced'

const server = fastify()

// Due to fastify-http-errors-enhanced using an onRoute hook, you must
// either use `await register` or wrap route definitions in a plugin.
await server.register(fastifyHttpErrorsEnhanced, {
  // Example options
  use422ForValidationErrors: true,
  hideUnhandledErrors: process.env.NODE_ENV === 'production'
})

server.get('/invalid', {
  handler: async function (request, reply) {
    throw new NotFoundError('This resource was not found.', {
      header: { 'X-Request-ID': request.id },
      code: 'RESOURCE_NOT_FOUND'
    })
  }
})

server.get('/ping', async (request, reply) => {
  return { status: 'ok' }
})

server.listen({ port: 3000 }, (err) => {
  if (err) {
    server.log.error(err)
    process.exit(1)
  }
  console.log(`Server listening on http://localhost:3000`)
})

view raw JSON →