{"id":16960,"library":"cli-handle-unhandled","title":"CLI Unhandled Rejection Handler","description":"cli-handle-unhandled is a specialized Node.js utility package designed for command-line interfaces (CLIs) to ensure graceful, yet explicit, termination upon encountering unhandled promise rejections. Currently stable at version 1.1.2, the package has a mature and focused scope, with infrequent but consistent maintenance releases since its initial launch. Its key differentiator lies in its opinionated approach: rather than merely logging an unhandled rejection and allowing the process to continue in an indeterminate state, it registers a handler that explicitly crashes the Node.js process, providing immediate feedback essential for robust CLI tooling. This prevents silent failures that can occur when asynchronous operations reject without a `.catch()` block, making errors transparent to the user or calling environment. It is primarily a CommonJS module, targeting Node.js environments.","status":"active","version":"1.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/ahmadawais/cli-handle-unhandled","tags":["javascript","cli-handle-unhandled","Ahmad Awais","ahmadawais"],"install":[{"cmd":"npm install cli-handle-unhandled","lang":"bash","label":"npm"},{"cmd":"yarn add cli-handle-unhandled","lang":"bash","label":"yarn"},{"cmd":"pnpm add cli-handle-unhandled","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is a CommonJS module. Direct ES Module imports are not supported without a CommonJS wrapper or bundler.","wrong":"import unhandledError from 'cli-handle-unhandled';","symbol":"unhandledError","correct":"const unhandledError = require('cli-handle-unhandled');"},{"note":"The package exports a function directly. It's typically invoked immediately to register the handler. Named imports are not applicable for its default (and only) export.","wrong":"import { cliHandleUnhandled } from 'cli-handle-unhandled';","symbol":"cliHandleUnhandled","correct":"const cliHandleUnhandled = require('cli-handle-unhandled');\ncliHandleUnhandled();"}],"quickstart":{"code":"const cliHandleUnhandled = require('cli-handle-unhandled');\n\n// Initialize the unhandled rejection handler\ncliHandleUnhandled();\n\nconsole.log('Application started. An unhandled promise rejection will occur in 1 second.');\n\nasync function simulateUnhandledRejection() {\n  return new Promise((resolve, reject) => {\n    setTimeout(() => {\n      console.log('Simulating an unhandled rejection...');\n      reject(new Error('This is an intentional unhandled rejection!')); // This will trigger cli-handle-unhandled\n    }, 1000);\n  });\n}\n\n// Call an async function without a .catch() to trigger an unhandled rejection\nsimulateUnhandledRejection();\n\n// Keep the process alive briefly to allow the promise to reject\nsetTimeout(() => {\n  console.log('This message should not appear if cli-handle-unhandled works.');\n}, 2000);","lang":"javascript","description":"Demonstrates how to initialize cli-handle-unhandled and triggers an unhandled promise rejection to show its intended behavior of crashing the process."},"warnings":[{"fix":"Understand that this package is meant to terminate the process on unhandled rejections. If you want to *prevent* crashes and handle rejections gracefully without exiting, use `process.on('unhandledRejection', (reason, promise) => { /* custom logging & recovery */ });` without `cli-handle-unhandled`.","message":"The primary function of `cli-handle-unhandled` is to cause the Node.js process to exit (crash) gracefully when an unhandled promise rejection occurs. It does not 'prevent' crashes but rather ensures that unhandled rejections lead to an explicit, observable failure state, which is often desired in CLI tools to avoid silent errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your project or file uses CommonJS `require()` to import this package, or configure your build system to handle CJS imports within an ESM context. For Node.js versions 12+, consider dynamic `import()` for CJS modules if absolutely necessary: `const cliHandleUnhandled = await import('cli-handle-unhandled'); cliHandleUnhandled.default();` (assuming a default export when dynamically imported).","message":"As a CommonJS module, `cli-handle-unhandled` must be imported using `require()`. Attempting to use ES Module `import` syntax in a pure ESM project without proper transpilation or wrapper might result in `ERR_REQUIRE_ESM`.","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":"Use `const cliHandleUnhandled = require('cli-handle-unhandled');` in CommonJS files, or configure your build system to properly handle CommonJS modules within an ES Module environment.","cause":"Attempting to `require()` an ES Module or using `import` for this CommonJS package in a project configured for ESM.","error":"Error [ERR_REQUIRE_ESM]: Must use import to load ES Module"},{"fix":"Ensure `cliHandleUnhandled()` is called early in your application's lifecycle. Check for other global `process.on('unhandledRejection', ...)` handlers that might be installed after `cli-handle-unhandled` and are preventing the intended crash.","cause":"This is typically the warning that `cli-handle-unhandled` is designed to intercept. If you see this warning without a subsequent process exit, it means the handler might not be properly installed or another global unhandled rejection handler is overriding it.","error":"(node:XXXX) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch()."}],"ecosystem":"npm","meta_description":null}