why-is-node-running
A debugging tool that identifies active handles keeping Node.js processes running when they should have exited.
What is why-is-node-running?
why-is-node-running is a debugging tool for Node.js that helps developers identify why their Node.js processes continue running when they should have exited. It detects active handles like open servers, timers, or other resources that prevent process termination, solving the common problem of mysterious process persistence and potential memory leaks.
Node.js developers and DevOps engineers who need to debug processes that won't exit, particularly those working on servers, long-running applications, or troubleshooting production issues.
Developers choose why-is-node-running because it provides immediate visibility into process lifecycle issues without complex setup, works in multiple modes (CLI, library, preload), and gives actionable stack traces to quickly identify the source of problems.
Overview
Node is running but you don't know why? why-is-node-running is here to help you.
Use Cases
Best For
- Debugging Node.js processes that won't exit after completing their work
- Identifying memory leaks caused by uncleared timers or open connections
- Troubleshooting production servers that accumulate handles over time
- Understanding why test suites or scripts hang indefinitely
- Debugging long-running processes in development environments
- Finding resource leaks in server applications and microservices
Not Ideal For
- Projects deployed on Windows that rely on signal-based triggering, as why-is-node-running uses Unix signals like SIGUSR1 which are not natively supported.
- Teams needing continuous, automated leak detection in production environments, since the tool requires manual intervention or signal sending to activate diagnostics.
- Applications heavily using Node.js worker threads or clusters, where handle detection might not seamlessly extend to isolated or multi-threaded contexts.
Pros & Cons
Pros
Supports multiple usage modes as a CLI tool, library dependency, or via Node.js' --import flag, allowing developers to choose the best fit for their workflow without code changes.
Shows file locations and call stacks for each detected handle, as seen in the example output, making it easy to pinpoint the exact source of process persistence.
Can be used with a single import and function call, or via CLI with npx, reducing setup time and enabling quick adoption in debugging sessions.
On supported systems like macOS, BSD, and Linux, it can be triggered via SIGUSR1/SIGINFO or Ctrl+T, allowing on-demand diagnostics without interrupting code execution.
Cons
The signal-based triggering is ineffective on Windows, limiting cross-platform use and requiring workarounds for environments without native signal support.
Developers must manually invoke the tool or send signals, which can miss intermittent or timing-dependent issues and isn't suited for automated monitoring.
Focuses on active handles like timers and servers, but may not detect all resource leaks, such as those from unhandled promises or memory not tied to handles.
Frequently Asked Questions
Related Projects
debugA tiny JavaScript debugging utility modelled after Node.js core's debugging technique. Works in Node.js and web browsers
0x🔥 single-command flamegraph profiling 🔥
leakage🐛 Memory leak testing for node.
llnodeAn lldb plugin for Node.js and V8, which enables inspection of JavaScript states for insights into Node.js processes and their core dumps.
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.