HTTP Errors Enhanced

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/http-errors-enhanced/dist/index.js from ... not supported. Instead change the require of index.js to a dynamic import() which is available in all CommonJS modules.

  cause Attempting to import `http-errors-enhanced` using CommonJS `require()` syntax in a Node.js environment.
  fix Convert your module to an ES Module (by setting `"type": "module"` in `package.json` or using `.mjs` extension) and use `import { ... } from 'http-errors-enhanced';` or use a dynamic import `import('http-errors-enhanced')`.

• The package 'http-errors-enhanced' requires Node.js version >= 22.21.0. The current Node.js version is v20.x.x.

  cause The installed version of `http-errors-enhanced` (v4.x.x) is not compatible with your current Node.js runtime.
  fix Upgrade your Node.js runtime to version 22.21.0 or higher. Use `nvm install 22 && nvm use 22` to switch Node.js versions if you have `nvm` installed.

• TypeError: HttpError is not a constructor

  cause This error typically occurs when trying to call `HttpError` as a function or without the `new` keyword, or if the import path is incorrect/module is not properly loaded.
  fix Ensure you are using the `new` keyword when instantiating `HttpError` (e.g., `new HttpError(...)`) or use the `createError` factory function (e.g., `createError(...)`). Verify your `import` statement is correct.

Warnings

• breaking Version 4.0.0 of `http-errors-enhanced` dropped support for Node.js 20. The package now requires Node.js version >= 22.21.0.
  Fix: Upgrade your Node.js runtime to version 22.21.0 or higher. Consider using a version manager like `nvm` (`nvm install 22 && nvm use 22`).
• breaking Version 3.0.0 of `http-errors-enhanced` dropped support for Node.js 18. This version requires Node.js 20 or higher.
  Fix: Upgrade your Node.js runtime to version 20 or higher. If targeting v4.x, upgrade to Node.js 22.21.0 or higher.
• gotcha When constructing an `HttpError` or using `createError`, invalid HTTP status codes (outside 400-599) or unrecognized string identifiers will default the error's status to 500 (Internal Server Error).
  Fix: Always use valid HTTP status codes (400-599) or the predefined string identifiers (e.g., 'NotFound', 'BadRequest') to ensure the correct error status is set.
• gotcha The `properties` object passed to error constructors or `createError` will ignore attempts to overwrite certain reserved error properties like `code`, `message`, `stack`, `expose`, and `headers` if they already exist on the error object. Only non-reserved or new properties will be added.
  Fix: If you need to customize reserved properties, some might be settable directly, but generally, use different property names for custom data to avoid conflicts.

Install

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

Imports

• HttpError
  wrong:

  const { HttpError } = require('http-errors-enhanced')

  correct:

  import { HttpError } from 'http-errors-enhanced'

  The library is ESM-only since v3.0.0, requiring `import` syntax.
• NotFoundError
  wrong:

  const { NotFoundError } = require('http-errors-enhanced')

  correct:

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

  Specific HTTP error classes like `NotFoundError` are named exports and follow ESM-only rules.
• createError
  wrong:

  const { createError } = require('http-errors-enhanced')

  correct:

  import { createError } from 'http-errors-enhanced'

  The `createError` factory function is a named export for convenience, adhering to ESM-only.

Quickstart

This quickstart demonstrates how to create various HTTP errors using the `HttpError` class, specific error classes like `NotFoundError`, and the `createError` factory function, showcasing custom properties and error chaining with `Error.cause`.

import { HttpError, NotFoundError, createError } from 'http-errors-enhanced';

// Demonstrate creating a generic HTTP error with a numeric status code and custom properties
const genericError = new HttpError(400, 'Invalid request parameters.', {
  requestId: 'abc-123',
  details: 'Missing required field: userId'
});
console.log('Generic Error:', genericError.status, genericError.message, genericError.requestId);

// Demonstrate creating a specific HTTP error by its class name, with custom message and properties
const notFoundError = new NotFoundError('Resource /users/123 not found.', {
  resource: '/users/123',
  userId: 'non-existent'
});
console.log('Not Found Error:', notFoundError.status, notFoundError.error, notFoundError.resource);

// Demonstrate using the createError factory function with a string identifier and properties
const badGatewayError = createError('BadGateway', {
  upstreamService: 'payment-gateway',
  responseCode: 502,
  message: 'Failed to connect to payment service.'
});
console.log('Bad Gateway Error:', badGatewayError.status, badGatewayError.errorPhrase, badGatewayError.upstreamService);

// Example of accessing built-in properties like isClientError
if (genericError.isClientError) {
  console.log('This is a client error and can potentially be exposed to the client.');
}

// You can also add a cause to errors (supported since v3.0.0)
const originalDbError = new Error('Database connection failed due to network timeout.');
const internalServerError = new HttpError(500, 'An unexpected error occurred processing your request.', {
  transactionId: 'xyz-456'
}, { cause: originalDbError });
console.log('Internal Server Error with cause:', internalServerError.cause?.message);