How do I debug Node.js internals?
Start from the JavaScript API in the lib directory, follow to the C++ bindings in src if needed, check libuv for I/O issues, read tests for expected behavior, use the Node.js debugger or a C++ debugger for deep issues, and check GitHub issues for known problems.
Verify This Answer
Cross-check this information using these trusted sources:
More FAQs in How to Debug Node.js Internals by Reading the Source
Find the JavaScript implementation of the API in the lib directory. Start there and trace what it does. If it calls a C++ binding, follow to the src directory to understand what the binding does.
Check libuv. For I/O issues like file system or network behavior, the answer is often in how the operation is delegated to libuv and how the callback is scheduled. The deps directory contains the bundled libuv source.
They show expected behavior. Check the test directory for how the feature is expected to behave. If your code differs from the tests, you found the issue. If the tests match but behavior differs, it may be a Node.js bug.
Still have questions?
Browse all our FAQs or reach out to our support team