why-is-node-running

Common errors

• Error [ERR_REQUIRE_ESM]: Must use import to load ES Module: ... why-is-node-running/index.js

  cause 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

  cause 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');`.

Warnings

• breaking Version 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`.
• gotcha When 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`.
• gotcha The 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.

Install

• npm install why-is-node-running npm
• yarn add why-is-node-running yarn
• pnpm add why-is-node-running pnpm

Imports

• whyIsNodeRunning
  wrong:

  const whyIsNodeRunning = require('why-is-node-running');

  correct:

  import whyIsNodeRunning from '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
  wrong:

  import 'why-is-node-running/include';

  correct:

  node --import why-is-node-running/include my-app.js

  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
  wrong:

  const whyIsNodeRunning: any = require('why-is-node-running');

  correct:

  import whyIsNodeRunning from 'why-is-node-running';
  import type { ActiveHandle } from '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.

Quickstart

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.');
});