Registry / observability / why-is-node-running

why-is-node-running

JSON →
library3.2.2jsnpmunverified

why-is-node-running is a diagnostic utility for Node.js environments, designed to identify active handles (like timers, network connections, and event listeners) that prevent a Node.js process from exiting gracefully. The current stable version is 3.2.2. Releases are active but somewhat irregular, typically driven by Node.js version updates or small feature enhancements and bug fixes. Its key differentiator lies in its ability to pinpoint the exact code locations responsible for these lingering handles, providing stack traces to aid in debugging unexpected process longevity or potential memory leaks, which is crucial for server-side applications and long-running scripts. It supports both programmatic integration and CLI usage, including a convenient `--import` flag for preloading. The package also provides TypeScript type definitions for enhanced developer experience.

npm install why-is-node-running
INSTALL
IMPORT
SIG · WHY-IS-NODE-RUNNIN
W
why-is-node-running
observabilityjavascriptv3.2.2
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

whyIsNodeRunning
import whyIsNodeRunning from 'why-is-node-running';
const whyIsNodeRunning = require('why-is-node-running');
Since v3.0.0, this package is ESM-only and requires Node.js 20.11 or higher. Direct `require()` statements will result in an `ERR_REQUIRE_ESM` error.
include entrypoint for --import
node --import why-is-node-running/include my-app.js
import 'why-is-node-running/include';
The `why-is-node-running/include` entrypoint is specifically designed for Node.js's `--import` CLI flag for preloading. Importing it directly in application code is not the intended use and may not yield the expected behavior or could lead to errors if not handled carefully within an ESM context.
Types
import whyIsNodeRunning from 'why-is-node-running'; import type { ActiveHandle } from 'why-is-node-running';
const whyIsNodeRunning: any = require('why-is-node-running');
The package ships with TypeScript type definitions. While the main export is a default function, specific types like `ActiveHandle` can be imported for detailed typing.

This quickstart demonstrates how to programmatically use `why-is-node-running` to identify open handles (like `setInterval` and `net.Server`) that prevent a Node.js process from exiting. It intentionally creates multiple handles and then uses `whyIsNodeRunning()` to print a detailed report of these active handles and their associated stack traces to the console.

import whyIsNodeRunning from 'why-is-node-running'; // Should be the first import for best results import { createServer } from 'node:net'; console.log('Starting application...'); // Function to simulate a long-running task or server function startServerAndInterval() { // A setInterval keeps the process alive setInterval(() => { // console.log('Interval running...'); }, 1000); // A TCP server also keeps the process alive const server = createServer(); server.listen(0, () => { const address = server.address(); console.log(`Server listening on port ${typeof address === 'string' ? address : address?.port}`); }); // Add a listener that might not be cleaned up process.on('SIGINT', () => { console.log('Received SIGINT. Shutting down...'); server.close(() => { console.log('Server closed.'); process.exit(0); }); }); } // Call the function multiple times to create several handles startServerAndInterval(); startServerAndInterval(); // Use setImmediate to log active handles after the current event loop turn // This will show what's keeping Node.js running. setImmediate(() => { console.log('\nChecking for active handles:'); whyIsNodeRunning(); console.log('\nIf the process does not exit, inspect the output above.'); });
why-is-node-running --version
Debug
Known issues
breakingVersion 3.0.0 of `why-is-node-running` introduced significant breaking changes by moving to ECMAScript Modules (ESM) only and raising the minimum required Node.js version to 20.11 or higher. This makes the package incompatible with CommonJS-based environments. Existing projects using `require()` will need to migrate to `import` statements or use `why-is-node-running@v2.x` for CommonJS compatibility.
fix
Migrate your project to use ES modules (`import` syntax and `"type": "module"` in `package.json`) or ensure your Node.js version is 20.11+. For CommonJS projects, explicitly install `why-is-node-running@2.x`.
affects: >=3.0.0
gotchaWhen using `why-is-node-running/include` for preloading, it must be specified via Node.js's `--import` CLI flag, not as a direct `import` statement within your application code. Attempting to `import 'why-is-node-running/include'` might lead to unexpected behavior or errors.
fix
Instead of `import 'why-is-node-running/include';` in your code, execute your Node.js application with `node --import why-is-node-running/include your-app.js`.
affects: >=3.0.0
gotchaThe output for file paths in stack traces became relative to the current working directory as of v3.2.0. While not a breaking change in functionality, users accustomed to absolute paths might notice a difference. Full absolute paths are still used if a file is outside the current working directory.
fix
Be aware that stack traces will now show relative paths for files within your project, which can be beneficial for readability across different environments. No fix is required, but adjust expectations for log parsing.
affects: >=3.2.0
Errors
Common errors & fixes
Error [ERR_REQUIRE_ESM]: Must use import to load ES Module: ... why-is-node-running/index.js
Attempting to `require()` `why-is-node-running` in a CommonJS module after upgrading to v3.0.0 or later.
fix
Update your code to use `import whyIsNodeRunning from 'why-is-node-running';` and ensure your project is configured for ESM (e.g., by adding `"type": "module"` to your `package.json` file or renaming files to `.mjs`). If migration is not feasible, downgrade to `why-is-node-running@2.x`.
TypeError: whyIsNodeRunning is not a function
Incorrect import of the default export, often trying to destructure a named export that doesn't exist, or a mismatch in ESM/CJS expectations.
fix
Ensure you are using a default import: `import whyIsNodeRunning from 'why-is-node-running';`. If in a CJS context (and using v2.x), it would be `const whyIsNodeRunning = require('why-is-node-running');`.
Upgrade
Version history
3.2.2latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
36 hits · last 30 days
node
28
OpenAI (training)
1
Resources
why-is-node-running — npm install why-is-node-running · libregistry