{"id":17227,"library":"fastify-http-errors-enhanced","title":"Fastify HTTP Errors Enhanced Plugin","description":"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.","status":"active","version":"7.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/ShogunPanda/fastify-http-errors-enhanced","tags":["javascript","fastify","fastify-plugin","http-errors","http-errors-enhanced","typescript"],"install":[{"cmd":"npm install fastify-http-errors-enhanced","lang":"bash","label":"npm"},{"cmd":"yarn add fastify-http-errors-enhanced","lang":"bash","label":"yarn"},{"cmd":"pnpm add fastify-http-errors-enhanced","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; this package is a plugin for Fastify applications.","package":"fastify","optional":false},{"reason":"Core runtime dependency; provides the enhanced HTTP error classes used and exposed by the plugin.","package":"http-errors-enhanced","optional":false}],"imports":[{"note":"The package is ESM-only and should be imported using `import` statements.","wrong":"const fastifyHttpErrorsEnhanced = require('fastify-http-errors-enhanced')","symbol":"fastifyHttpErrorsEnhanced","correct":"import fastifyHttpErrorsEnhanced from 'fastify-http-errors-enhanced'"},{"note":"Error classes like NotFoundError are re-exported from `http-errors-enhanced`, not the plugin itself.","wrong":"import { NotFoundError } from 'fastify-http-errors-enhanced'","symbol":"NotFoundError","correct":"import { NotFoundError } from 'http-errors-enhanced'"},{"note":"This type can be imported for configuring the plugin options with TypeScript.","symbol":"FastifyHttpErrorsEnhancedOptions","correct":"import type { FastifyHttpErrorsEnhancedOptions } from 'fastify-http-errors-enhanced'"}],"quickstart":{"code":"import fastify from 'fastify'\nimport fastifyHttpErrorsEnhanced from 'fastify-http-errors-enhanced'\nimport { NotFoundError } from 'http-errors-enhanced'\n\nconst server = fastify()\n\n// Due to fastify-http-errors-enhanced using an onRoute hook, you must\n// either use `await register` or wrap route definitions in a plugin.\nawait server.register(fastifyHttpErrorsEnhanced, {\n  // Example options\n  use422ForValidationErrors: true,\n  hideUnhandledErrors: process.env.NODE_ENV === 'production'\n})\n\nserver.get('/invalid', {\n  handler: async function (request, reply) {\n    throw new NotFoundError('This resource was not found.', {\n      header: { 'X-Request-ID': request.id },\n      code: 'RESOURCE_NOT_FOUND'\n    })\n  }\n})\n\nserver.get('/ping', async (request, reply) => {\n  return { status: 'ok' }\n})\n\nserver.listen({ port: 3000 }, (err) => {\n  if (err) {\n    server.log.error(err)\n    process.exit(1)\n  }\n  console.log(`Server listening on http://localhost:3000`)\n})\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"`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`).","severity":"breaking","affected_versions":">=7.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.","message":"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.","severity":"breaking","affected_versions":">=6.0.0 <7.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"The installed Node.js version is older than the minimum requirement for the current `fastify-http-errors-enhanced` version.","error":"Error: fastify-http-errors-enhanced requires Node.js version >= 22.21.0"},{"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.","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`.","error":"TypeError: server.addHook is not a function"}],"ecosystem":"npm","meta_description":null}