Node.js HTTP Error Handling

2.0.0 verified Thu Apr 23 auth: no javascript abandoned

node-http-error provides a simple mechanism for creating and throwing HTTP-specific errors within Node.js applications, particularly useful for API development with frameworks like Express. This package allows developers to instantiate errors with a given HTTP status code, an optional custom message, and additional properties, while also automatically generating default messages for standard status codes. Key features of version 2.0.0, released in 2014, include full stack traces, the ability to omit the `new` operator when creating instances, and direct access to `status` and `statusCode` properties for integration with error handling middleware. However, this specific package by carsondarling is considered abandoned, with its last update occurring nine years ago. Developers are strongly encouraged to use more actively maintained alternatives like `http-errors` (from `jshttp`) for modern Node.js projects.

Common errors

error ReferenceError: require is not defined ↓

cause Attempting to use `require()` in an ES Module (ESM) context without a CommonJS compatibility layer.

fix

This package is CommonJS-only. Either refactor your project to use CommonJS, use dynamic import() (if compatible with your setup), or, preferably, migrate to a modern, actively maintained HTTP error library that supports ESM.

error TypeError: app.use() requires a middleware function but got a undefined ↓

cause The `HTTPError` object (or the `node-http-error` module itself) failed to load or was incorrectly referenced, resulting in `undefined` being passed where a function was expected.

fix

Ensure require('node-http-error') correctly resolves and that HTTPError is accessible in your scope. Verify file paths and npm installation. Given the package's age, ensure your Node.js environment is not causing compatibility issues during module loading.

Warnings

breaking The `node-http-error` package (by carsondarling) has been abandoned since 2014. It receives no updates, bug fixes, or security patches, making it unsuitable for new projects or production environments. ↓

fix Migrate to a currently maintained alternative like `http-errors` (from `jshttp`) or `@curveball/http-errors`, which offer similar functionality with active development and modern JavaScript support.

breaking This package is CommonJS-only. It cannot be directly imported into ES Module (ESM) contexts using `import` statements, leading to `ReferenceError: require is not defined`. ↓

fix For ESM projects, use an actively maintained package that provides ESM compatibility. If you must use this package in an ESM context, consider dynamic `import()` or transpilation, but migration is strongly recommended.

gotcha The package's reliance on older Node.js HTTP module behavior might be incompatible with stricter HTTP parser changes introduced in Node.js v12 and later, potentially leading to unexpected error handling or server behavior. ↓

fix Upgrade to a modern HTTP error utility that is actively tested and maintained with current Node.js versions.

Install

npm install node-http-error

yarn add node-http-error

pnpm add node-http-error

Imports

HTTPError
wrong
```
import { HTTPError } from 'node-http-error';
```
correct
```
const HTTPError = require('node-http-error');
```
This package (v2.0.0) is CommonJS only and does not provide ES Module exports. Attempting an ESM import will result in a runtime error.
HTTPError (function call)
wrong
```
next(new HTTPError(500, 'Error by design.'));
```
correct
```
next(HTTPError(500, 'Error by design.'));
```
While `new HTTPError()` works, the library explicitly supports calling `HTTPError()` as a function without `new` for convenience and brevity, as shown in the original documentation.

Quickstart

This quickstart demonstrates how to create and throw `HTTPError` instances within an Express.js application, and how to set up a basic error handling middleware to catch and respond to these errors using their status code and message.

const HTTPError = require('node-http-error');
const express = require('express');
const app = express();

app.get('/error', function(req, res, next) {
  // Example of throwing a 500 Internal Server Error with a custom message
  return next(new HTTPError(500, 'Error by design.'));
});

app.get('/not-found', function(req, res, next) {
  // Example of throwing a 404 Not Found error using only the status code
  return next(HTTPError(404)); 
});

// Error handler middleware
app.use(function(err, req, res, next) {
  if (err instanceof HTTPError) {
    res.status(err.status || err.statusCode || 500);
    res.send(err.message || 'An unexpected error occurred.');
  } else {
    res.status(500).send('Unhandled server error.');
  }
});

app.listen(3000, () => {
  console.log('Server listening on http://localhost:3000');
  console.log('Try visiting http://localhost:3000/error');
  console.log('Try visiting http://localhost:3000/not-found');
});