Common Error Classes for Node.js

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported.

  cause Attempting to `require()` an ES Module or attempting to `import` a CommonJS module (like `common-errors`) directly in an ESM context without proper configuration.
  fix If `common-errors` is the CJS module: use `const errors = require('common-errors');`. If your project is ESM and you need to consume this CJS module, ensure Node.js interoperability is configured, or use a dynamic `import()` if suitable.

• ReferenceError: errors is not defined

  cause The main `common-errors` module, often imported as `errors`, was not correctly `require()`d or `import`ed before use.
  fix Add `const errors = require('common-errors');` at the top of your file to make the error classes available.

• TypeError: Class extends value undefined is not a constructor or null

  cause This can occur if `errors.generateClass` is called with an invalid base class or if the `errors` object itself is `undefined` due to an incorrect import. It can also happen when attempting to extend a non-constructor.
  fix Verify that `common-errors` is correctly `require()`d and that `generateClass` is used with valid arguments. Ensure the base class (second argument) if provided, is a valid constructor function.

• Error: Cannot find module 'common-errors'

  cause The `common-errors` package is not installed in the project's `node_modules` directory or there's a typo in the `require()` path.
  fix Run `npm install common-errors` to install the package. Double-check the module name in your `require()` statement.

Warnings

• breaking This package is effectively abandoned. The last version (1.2.0) was published 9 years ago (as of April 2026). This means there will be no new features, bug fixes, or security patches.
  Fix: Consider migrating to a more actively maintained error utility library or implementing custom error classes yourself. Evaluate security implications carefully.
• gotcha The package is primarily a CommonJS module and does not natively support ES Module (`import`) syntax. Attempting to `import` it directly in a modern ESM-only project will likely result in `ERR_REQUIRE_ESM` or similar errors.
  Fix: Use `const errors = require('common-errors');` for CommonJS environments. For ESM projects, you might need Node.js's interoperability features or a bundler to consume this CJS package, or use dynamic `import()` if applicable.
• gotcha Due to its age (last updated 2017), `common-errors` may not be fully compatible with very recent Node.js versions or modern JavaScript language features (e.g., `async/await` error handling patterns).
  Fix: Thoroughly test compatibility with your target Node.js version. If issues arise, consider alternative, more modern error handling libraries.
• breaking The lack of maintenance implies potential unaddressed security vulnerabilities. Using abandoned software in production can expose applications to risks.
  Fix: Perform a security audit of your dependencies. If security is critical, replacing this library with a maintained alternative is strongly recommended.

Install

• npm install common-errors npm
• yarn add common-errors yarn
• pnpm add common-errors pnpm

Imports

• errors
  wrong:

  import * as errors from 'common-errors';

  correct:

  const errors = require('common-errors');

  This package is a CommonJS module from an older era. Direct ESM `import` will likely fail without specific Node.js configuration (e.g., 'type: module' in package.json or transpilation).
• ArgumentError
  wrong:

  import { ArgumentError } from 'common-errors';

  correct:

  const { ArgumentError } = require('common-errors');

  While CommonJS modules can often be destructured, using `require` for this older library is safer than an ESM `import` directly. The library's structure (`errors.ArgumentError`) suggests a single primary export.
• generateClass
  wrong:

  import { generateClass } from 'common-errors';

  correct:

  const { generateClass } = require('common-errors');

  As a utility function, it's typically accessed via the main `errors` object or potentially destructured from the `require` call. ESM `import` is not natively supported.

Quickstart

Demonstrates the creation and catching of various common error types, custom error generation, and the utility for prepending stack traces from inner errors.

const errors = require('common-errors');

try {
  // Example 1: Argument Null Error
  function processUser(username) {
    if (!username) {
      throw new errors.ArgumentNullError('username');
    }
    console.log(`Processing user: ${username}`);
  }
  processUser(null);
} catch (error) {
  console.error('Caught ArgumentNullError:', error.name, error.message);
  console.error(error.stack);
}

try {
  // Example 2: Custom Error Generation
  const MyCustomError = errors.generateClass('MyCustomError', 'CustomErrorBase');
  throw new MyCustomError('Something went wrong in my custom component!');
} catch (error) {
  console.error('Caught MyCustomError:', error.name, error.message);
}

// Example 3: Error with inner error and stack prepending
function fetchData() {
  try {
    throw new Error('Original underlying database error');
  } catch (err) {
    // Prepend the current stack to the inner error's stack
    const connectionError = new errors.ConnectionError('Failed to connect to DB.', errors.prependCurrentStack(err));
    throw connectionError;
  }
}

try {
  fetchData();
} catch (error) {
  console.error('Caught ConnectionError with inner error:', error.name, error.message);
  console.error('Full stack:', error.stack);
}