This error indicates an internal bug in Node.js or incorrect usage of Node.js internals. When an assertion in the Node.js engine fails, it results in a crash with details about what went wrong. These errors are typically caused by edge cases in network operations, module loading, or worker thread handling.
The InternalError "Assertion failed" message indicates that an internal check in the Node.js JavaScript engine or runtime has failed. This is different from application-level errors—it represents a condition that Node.js developers did not expect to encounter during normal operation. In most cases, this error falls into two categories: either there is a bug in Node.js itself (which should be reported to the Node.js project), or your application is using Node.js internals in an unusual or edge-case way that triggers unexpected behavior. Common areas where this error appears include network connection handling (particularly in socket and DNS operations), module loading and ESM import resolution, worker thread message passing, and cryptographic operations. The error message usually includes a stack trace that points to the exact internal function that failed the assertion.
First, obtain the full error output so you can understand exactly where the assertion failed:
# Run your Node.js application with full error output
node --trace-uncaught app.js 2>&1 | tee error.log
# Or capture to a file for inspection
node app.js > error.log 2>&1The stack trace will show the exact function in Node.js internals where the assertion failed. Look for patterns like:
- internalConnect - connection handling issue
- internalConnectMultiple - multi-address connection attempt
- "Assertion failed" messages with additional context
Save this output—you'll need it for troubleshooting or reporting to Node.js.
Many internal assertions have been fixed in newer Node.js releases. Upgrade to see if the issue is already resolved:
# Check current Node.js version
node --version
# Update using nvm (recommended)
nvm install --latest-lts
nvm use --latest-lts
# Or update using Homebrew (macOS)
brew upgrade node
# Or download from nodejs.org and reinstall
# https://nodejs.org/After upgrading, test your application thoroughly. Many "Assertion failed" errors from older Node.js versions are fixed in newer releases.
Try to isolate what operation triggers the assertion failure:
// Example: If the error happens during connections, test connections in isolation
const net = require('net');
const client = new net.Socket();
client.connect(3000, 'localhost', () => {
console.log('Connected');
client.destroy();
});
client.on('error', (err) => {
console.error('Connection error:', err);
});
client.on('timeout', () => {
console.log('Connection timeout');
client.destroy();
});
// Set a timeout to catch if assertion fails
setTimeout(() => {
console.log('Test completed without assertion failure');
process.exit(0);
}, 5000);Knowing exactly which operation triggers the error helps determine if it's your code or Node.js internals.
The assertion failure might only occur under specific load conditions. Test your application with realistic concurrency:
// Monitor memory usage
const { performance } = require('perf_hooks');
console.log('Memory at start:', process.memoryUsage());
// Run your operation
const start = performance.now();
// ... your code ...
const end = performance.now();
console.log('Memory at end:', process.memoryUsage());
console.log('Time taken:', end - start, 'ms');
// If memory grows unbounded, it might trigger internal checks
setInterval(() => {
const mem = process.memoryUsage();
if (mem.heapUsed > 1000 * 1024 * 1024) { // 1GB
console.warn('High memory usage detected:', mem);
}
}, 1000);If the error only happens under high memory or connection load, you may need to restructure your application to limit concurrency or add resource cleanup.
If you use native modules (node-gyp compiled), they might leave Node.js internals in an invalid state:
# List installed native modules (packages with `binding.node`)
npm ls | grep "binding.node"
# Try removing native modules temporarily
npm uninstall package-name
# Test if the assertion still occurs
node app.jsIf removing a native module fixes the issue, the problem is in that module. Report the issue to that package's maintainers or find an alternative package.
Node.js can output detailed internal debugging information:
# Enable various debug modules
NODE_DEBUG=net,http,cluster node app.js
# Enable debug output for DNS operations
NODE_DEBUG=dns node app.js
# Enable debugging for worker threads
NODE_DEBUG=worker_threads node app.js
# Combine multiple debuggers
NODE_DEBUG=net,dns,http node app.jsThis output shows internal state transitions and can help identify what Node.js internals are doing when the assertion fails.
If you can reproduce the assertion failure consistently and it persists in the latest Node.js version, report it to the Node.js project:
# Create a minimal reproducible example in a separate file
cat > minimal-repro.js << 'EOF'
// Your minimal code that triggers the assertion
EOF
# Visit https://github.com/nodejs/node/issues
# Create a new issue with:
# 1. Node.js version (node --version)
# 2. Operating system
# 3. Minimal reproducible code
# 4. Full error stack trace
# 5. Steps to reproduceInclude the output from node --version and node --versions to show exact versions of all dependencies. A well-detailed bug report helps Node.js maintainers fix the issue.
Understanding Node.js Assertion Failures
Node.js assertions are internal sanity checks. When an assertion fails, it means Node.js detected a state it shouldn't be possible to reach. Examples include:
- A connection socket in an unexpected state
- A module with an invalid metadata status
- A worker thread receiving a message type it shouldn't handle
Common Contexts for Assertion Failures
1. Network Operations: Most common in net.internalConnectMultiple() when handling connection failures, timeouts, or unusual socket states. This often happens with:
- Multiple simultaneous connection attempts
- Rapid connect/disconnect cycles
- Connections to unavailable hosts with specific timeout patterns
2. Module Loading: Assertions can fail during ESM (ECMAScript Module) loading when modules have unexpected status values or circular dependencies interact badly with dynamic imports.
3. Worker Threads: Worker message passing can trigger assertions if the message queue or thread state becomes corrupted through unusual patterns.
Investigating with Node.js Flags
Use these Node.js command-line flags for deeper investigation:
# Enable all debugging
node --inspect app.js
# Connect with Chrome DevTools at chrome://inspect
# Enable core dump on crash (Linux)
ulimit -c unlimited
node app.js
# Analyze core dump
gdb node coreVersion-Specific Issues
Internal assertion errors are often specific to Node.js versions. Always check:
- Node.js release notes for your version
- GitHub issues for "ERR_INTERNAL_ASSERTION" with your symptoms
- Whether the issue is fixed in newer LTS versions
When It's Your Code
Less commonly, assertions can be triggered by:
- Using private/undocumented Node.js APIs
- Modifying prototypes of Node.js internals
- Extreme edge cases like millions of simultaneous connections
- Monkey-patching Node.js internal modules
If you suspect your code is the cause:
- Review any monkey-patching or prototype modifications
- Avoid using private APIs starting with _
- Test with vanilla Node.js without custom modifications
- Check if removing specific libraries fixes the issue
Recovery Strategies
If you can't immediately update Node.js:
1. Limit concurrency (max connection pools, worker thread counts)
2. Add timeouts aggressively
3. Restart the process periodically (use a process manager like PM2)
4. Monitor for early signs of the issue (unusual error patterns)
Error: EMFILE: too many open files, watch
EMFILE: fs.watch() limit exceeded
Error: Middleware next() called multiple times (next() invoked twice)
Express middleware next() called multiple times
Error: Worker failed to initialize (worker startup error)
Worker failed to initialize in Node.js
Error: EMFILE: too many open files, open 'file.txt'
EMFILE: too many open files
Error: cluster.fork() failed (cannot create child process)
cluster.fork() failed - Cannot create child process