Registry / observability / wtfnode

wtfnode

JSON →
library0.10.1jsnpmunverified

wtfnode is a utility designed to help Node.js developers diagnose why their applications are not exiting gracefully. It provides enhanced and human-readable insights into active event loop handles, such as timers, sockets, and servers, which prevent a Node.js process from terminating. Leveraging Node's internal `process._getActiveHandles()`, wtfnode breaks down complex handle information into actionable details, including call site origins for listeners, making it easier to pinpoint the exact code keeping a program alive. The current stable version, 0.10.1, functions as a crucial diagnostic tool for stalled applications, differentiating itself from raw Node.js introspection by offering a higher-level, more interpretable view of the event loop. Its release cadence is driven by the community's need for robust debugging solutions for persistent processes.

observability
npm install wtfnode
github ↗package ↗
INSTALL
IMPORT
SIG · WTFNODE
W
wtfnode
observabilityjavascriptv0.10.1
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.

wtf
✓ const wtf = require('wtfnode');
✗ import wtf from 'wtfnode';
Primarily designed for CommonJS; direct ESM import might not work as expected in older Node environments due to the package's age (v0.10.x). Use `require()` for consistency.
dump
✓ wtf.dump();
✗ require('wtfnode').dump();
The `dump()` method is the primary API for printing open handles. It should be called on the imported `wtf` object.
Options
✓ wtf.dump({ fullstacks: true });
✗ wtf.dump(true);
Options for `dump()` are passed as an object, not as direct arguments. `--fullstacks` is a command-line option, `fullstacks: true` is for the module API.

Demonstrates module usage by setting up a `setInterval` and an HTTP server, then using `wtf.dump()` to report open handles when the process receives a SIGINT signal.

const wtf = require('wtfnode'); console.log('Starting wtfnode example. Press Ctrl+C to dump handles.'); // Create an interval to keep the process alive const intervalId = setInterval(() => { console.log('Interval running...'); }, 2000); // Create a server that will also keep the process alive const http = require('http'); const server = http.createServer((req, res) => { res.writeHead(200, { 'Content-Type': 'text/plain' }); res.end('Hello wtfnode!\n'); }); server.listen(3000, () => { console.log('HTTP server listening on port 3000.'); }); // Register SIGINT handler to dump handles before exiting process.on('SIGINT', () => { console.log('\n[WTF Node?] Dumping open handles:'); wtf.dump(); // To allow clean exit after dump (optional, depending on desired behavior) clearInterval(intervalId); server.close(() => { console.log('Server closed. Exiting process.'); process.exit(0); }); }); console.log('Application running. Check http://localhost:3000 and wait for intervals.');
wtfnode --version
Debug
Known issues
gotchaWhen `wtfnode` reports on timers, the function name may appear as `wrapper` instead of the original function name. This is a limitation due to how `setInterval` and `setTimeout` create internal wrappers.
fix
Manually inspect the provided source line and context to identify the original function or module creating the timer.
affects: >=0.1.0
gotchaThe `IPC channel to parent` handle provides limited information if your program is spawned by another process (e.g., `child_process.fork`, PM2). `wtfnode` cannot extract more context as it's not based on code executed within the current program.
fix
Investigate the parent process that spawned the current application to understand why the IPC channel remains open.
affects: >=0.1.0
breakingIn version 0.4.0, a change was introduced for command-line usage (`wtfnode <yourscript>`). If the target script binds SIGINT and enters an infinite loop, Node.js might not exit. `wtfnode` now uses a watchdog proxy, allowing two Ctrl+C presses to force termination, though no output will be available.
fix
Press Ctrl+C twice to force-terminate processes stuck in infinite loops when using `wtfnode` globally. For module usage, ensure your SIGINT handler allows for `wtf.dump()` to complete and the process to exit.
affects: >=0.4.0
gotchaWhen using `wtfnode` from a child process on Node.js version 0.12, you might briefly see an `unable to determine callsite` warning due to transient child process handles. This is generally harmless.
fix
This warning can typically be ignored. If persistent, try delaying the call to `wtf.dump()` slightly within the child process.
affects: =0.12.x
Errors
Common errors & fixes
Process never exits / Application hangs indefinitely
One or more event loop handles (e.g., timers, network connections, open file descriptors) are still active, preventing Node.js from shutting down.
fix
Add `wtfnode` to your application and call `wtf.dump()` when you suspect the process should exit (e.g., on `SIGINT` or at the end of a long-running task) to identify the specific open handles.
WTF Node? open handles: Timers: - (Xms ~ Ys) wrapper @ /path/to/module.js:Line
An `setInterval` or `setTimeout` call is still active, reported as a generic `wrapper` function.
fix
Examine the `module.js:Line` indicated in the output. This line points to where the timer was originally set. Ensure all long-running timers are explicitly cleared when no longer needed using `clearInterval()` or `clearTimeout()`.
WTF Node? open handles: Sockets: - A.B.C.D:PORT -> W.X.Y.Z:PORT Listeners: connect: anonymous @ /path/to/connection.js:Line
An open network socket or server connection is preventing the process from exiting. The listener shows where the connection handler was defined.
fix
Locate the code at `/path/to/connection.js:Line` to identify the socket's origin. Ensure all database connections, HTTP servers, or other network resources are explicitly closed or terminated when your application is done with them.
Upgrade
Version history
0.10.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
38 hits · last 30 days
node
30
OpenAI (training)
1
Resources
githubhttps://github.com/myndzi/wtfnode ↗
packagehttps://www.npmjs.com/package/wtfnode ↗
wtfnode — npm install wtfnode · libregistry