Registry / observability / handle-cli-error

handle-cli-error

library6.2.0jsnpmunverified

handle-cli-error is a robust error handling library specifically designed for Node.js command-line interface (CLI) applications. It provides a comprehensive solution for displaying errors to users in a clear, consistent, and visually appealing manner, then gracefully exiting the process. The current stable version is 6.2.0, with frequent minor releases introducing new features and improvements, such as enhanced customization options. Key differentiators include its ability to generate pretty, colorized error output with icons and headers, support for error class-specific handling (allowing different exit codes or logging behaviors per error type), graceful process exit with customizable timeouts, and automatic normalization of invalid Error objects using `normalize-exception`. It also allows fine-grained control over what error details are logged, such as stack traces, nested error causes, and additional error properties, making it highly configurable for various CLI needs.

observability

npm install handle-cli-error

github ↗package ↗

INSTALL

IMPORT

SIG · HANDLE-CLI-ERROR

handle-cli-error

observabilityjavascriptv6.2.0

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.

handleCliError

✓ import handleCliError from 'handle-cli-error'

✗ const handleCliError = require('handle-cli-error')

handle-cli-error is an ES module and must be imported using `import` syntax. CommonJS `require` is not supported.

Options

✓ import type { Options } from 'handle-cli-error'

TypeScript users can import the `Options` type for strong typing of the configuration object.

handleCliError (named import)

✓ import { handleCliError } from 'handle-cli-error'

✗ import * as handleCliError from 'handle-cli-error'

The main function is exported as the default, but also as a named export for consistency with some bundlers or preferences.

Demonstrates basic usage of `handleCliError` within a try-catch block, including error class-specific options and custom configuration for output.

import handleCliError from 'handle-cli-error'; const main = async () => { try { // Simulate a CLI operation that might fail const result = await Promise.resolve('some_data'); if (result !== 'expected_data') { throw new Error('Unexpected data received. This is a critical error.', { cause: 'Data mismatch' }); } console.log('CLI operation successful!'); } catch (error) { handleCliError(error, { classes: { TypeError: { exitCode: 1, stack: false, props: false }, Error: { exitCode: 2, cause: true }, default: { exitCode: 3, colors: true, silent: process.env.NODE_ENV === 'test' }, }, header: 'CLI Error: {name}', // Custom header format exitCode: 99, // Fallback exit code }); } }; main();

Debug

Known issues

breakingThe package `handle-cli-error` is an ES module (ESM) only since version 5.0.0. It must be imported using `import` statements and cannot be loaded with CommonJS `require()`.

fix

Ensure your project is configured for ESM, typically by setting `"type": "module"` in your `package.json` or by using `.mjs` file extensions. Replace all `require('handle-cli-error')` with `import handleCliError from 'handle-cli-error'`.

affects: >=5.0.0

breakingMinimal supported Node.js version is now `18.18.0`.

fix

Upgrade your Node.js runtime to version `18.18.0` or newer. If you are on an older Node.js version, you will need to stick to `handle-cli-error` v4.x.

affects: >=5.0.0

breakingIn v6.0.0, the `props` option no longer controls the printing of nested errors (`error.cause` and `error.errors`). A new dedicated `cause` option was introduced for this purpose.

fix

If you previously relied on `props: false` to hide nested errors, you must now explicitly set `cause: false` instead. The `props` option now strictly controls additional error properties, not nested errors.

affects: >=6.0.0

gotchaWhen customizing error output with `error.beautiful(output)` (since v6.1.0) or the `custom` option (since v6.2.0), ensure your method returns a string. Returning `undefined` or a non-string value may lead to unexpected output or errors.

fix

Always return a string from your `beautiful` method or the function specified by the `custom` option. For example: `class MyError extends Error { beautiful = (output) => `Customized: ${output}`; }`

affects: >=6.1.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM

Attempting to `require()` an ES module (`handle-cli-error`) in a CommonJS context.

fix

Migrate your file to ES modules by changing its extension to `.mjs` or by adding `"type": "module"` to your `package.json`. Then, use `import handleCliError from 'handle-cli-error'`.

Error: Cannot find module 'handle-cli-error'

Incorrect module resolution, often due to CommonJS environment attempting to load an ESM-only package or a broken `node_modules` installation.

fix

First, ensure `npm install handle-cli-error` ran successfully. If your project is CommonJS, review the `ERR_REQUIRE_ESM` warning. Also, try deleting `node_modules` and `package-lock.json`, then reinstalling dependencies.

TypeError: handleCliError is not a function

Attempting to call `handleCliError` after an incorrect CommonJS `require()` or a mistaken named import when the module provides a default export.

fix

Ensure you are using the correct ESM default import: `import handleCliError from 'handle-cli-error'`. If using TypeScript, check your `tsconfig.json` for `"module": "Node16"` or `"NodeNext"` and `"esModuleInterop": true`.

The 'cause' option cannot be combined with 'props' in this way. See documentation for breaking changes in v6.0.0.

Confusion or misuse of the `props` and `cause` options after the v6.0.0 breaking change where `cause` was introduced for nested errors.

fix

The `props` option now controls only additional error properties, while `cause` controls nested errors (`error.cause` and `error.errors`). Set `cause: false` to hide nested errors, not `props: false`.

Upgrade

Version history

6.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

18 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ehmicky/handle-cli-error ↗

packagehttps://www.npmjs.com/package/handle-cli-error ↗