Registry / web-framework / fastify-http-errors-enhanced

fastify-http-errors-enhanced

library7.0.1jsnpmunverified

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.

web-framework http-networking observability

npm install fastify-http-errors-enhanced

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FASTIFY-HTTP-ERROR

fastify-http-errors-enhanced

web-frameworkjavascriptv7.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

fastifyHttpErrorsEnhanced

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

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

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

NotFoundError

✓ import { NotFoundError } from 'http-errors-enhanced'

✗ import { NotFoundError } from 'fastify-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.

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`) })

Debug

Known issues

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.

affects: >=7.0.0

breakingVersion 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.

affects: >=6.0.0 <7.0.0

gotchaDue 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.

affects: >=1.0.0

gotchaThe `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`.

affects: >=1.0.0

Errors

Common errors & fixes

Error: fastify-http-errors-enhanced requires Node.js version >= 22.21.0

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

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.

Upgrade

Version history

7.0.1latest on npm

Audit

Dependencies

fastifyrequiredPeer dependency; this package is a plugin for Fastify applications.

http-errors-enhancedrequiredCore runtime dependency; provides the enhanced HTTP error classes used and exposed by the plugin.

Agent activity

18 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ShogunPanda/fastify-http-errors-enhanced ↗

packagehttps://www.npmjs.com/package/fastify-http-errors-enhanced ↗

homepagehttps://sw.cowtech.it/fastify-http-errors-enhanced ↗