A segmentation fault occurs when Node.js or a native addon attempts to access memory it is not permitted to access, causing the process to crash with a "Segmentation fault (core dumped)" message. This typically indicates a bug in native C/C++ modules rather than JavaScript code.
A segmentation fault (often abbreviated as "segfault" or "SIGSEGV") is a critical error that happens when a program tries to access a memory location that is either: - Not allocated for its use - Already freed or deallocated - Protected by the operating system - Beyond the bounds of an allocated memory region In Node.js, segmentation faults are serious because they cause the entire process to crash immediately without a proper JavaScript stack trace. Unlike other JavaScript errors that can be caught and handled, a segfault terminates Node completely. The error message "Segmentation fault (core dumped)" means the OS has forcibly terminated the process. The core dump is a memory image that can be analyzed by debuggers to identify the crash location.
Find all native modules by searching for compiled .node files:
# List all native modules
find node_modules -name "*.node" -type f | head -20
# Or use npm to list packages with native addons
npm list --depth=0 | grep -E '(node-gyp|native|addon)'Native modules are the primary cause of segmentation faults. Identify which modules are present in your project.
Rebuild native modules to ensure they are compiled against your current Node.js version:
# Clear npm cache
npm cache clean --force
# Rebuild all native modules
npm rebuild
# Or rebuild a specific module
npm rebuild module-nameThis recompiles native code against your current Node.js ABI (Application Binary Interface). Version mismatches are a common cause of segfaults.
Update packages that contain native addons:
# Update all packages
npm update
# Or update a specific native module
npm install module-name@latest
# Check outdated packages
npm outdatedNewer versions often fix bugs in native code that cause crashes. If you recently upgraded Node.js, ensure all native modules are updated too.
Isolate the problematic module by temporarily removing native packages:
# List your dependencies
npm list --depth=0
# Remove suspicious modules one at a time
npm uninstall problematic-module
# Run your app and test
node your-app.jsIf the segfault disappears after removing a module, that module is the culprit. Then you can:
- Update it to a newer version
- Find an alternative package
- File a bug report with the maintainer
Enable core dumps to capture detailed crash information:
# On Linux, increase core dump limit
ulimit -c unlimited
# Run your Node.js app
node your-app.js
# A "core" file will be created if a crash occurs
# Analyze with gdb
gdb node core
# In gdb, type: backtrace
# This shows where in the native code the crash occurredCore dumps provide detailed information that can be shared with module maintainers.
Install the segfault-handler module to capture native stack traces:
npm install segfault-handlerThen add to the start of your application:
import segfaultHandler from 'segfault-handler';
// Setup handler at the very beginning
segfaultHandler.registerHandler('crash.log');
// Rest of your app code
import express from 'express';
const app = express();
// ... your codeWhen a segfault occurs, a native stack trace is written to crash.log, helping identify the exact location of the crash in native code.
If segfaults started after upgrading Node.js, try reverting to a stable LTS version:
# Check your current version
node --version
# Install a specific LTS version using nvm
nvm install 20 # Latest LTS
# Switch to it
nvm use 20
# Rebuild native modules for new version
npm rebuildNode.js new releases sometimes have bugs. Using an LTS (Long-Term Support) version is safer for production.
Search for the segfault in relevant repositories:
# Get more details about the crash (if core dump is available)
# Search the affected module's GitHub issues
# Example: If crash is with 'sqlite3'
# Visit: https://github.com/mapbox/node-sqlite3/issues
# Search for "segmentation fault" or "SIGSEGV"Often the issue is known and has a fix or workaround documented.
Understanding Memory Safety in Node.js
Native modules are written in C/C++ without the memory safety protections of JavaScript. They have direct access to memory and can:
- Allocate and free memory
- Access pointers and memory addresses
- Call system-level functions
A single bug in native code—like writing past a buffer boundary or accessing freed memory—causes a segmentation fault that crashes the entire Node.js process.
Using GDB for Detailed Analysis
For deep debugging, compile Node.js with debug symbols and use GDB:
# Run Node with gdb
gdb --args node your-app.js
# In gdb, start execution
(gdb) run
# After crash occurs
(gdb) backtrace
# See detailed local variables
(gdb) info localsThis reveals the exact function and line in native code where memory was accessed illegally.
Native Module Security Considerations
Native modules introduce security and stability risks:
- They can bypass JavaScript sandbox protections
- They have direct system access
- A bug can crash your entire application
- They may have different security update cycles than Node.js
Always use native modules only when necessary and from trusted maintainers.
Common Native Module Issues by Node.js Version
- Node.js 14+: Some older native modules break due to changes in the V8 engine
- Node.js 18: HTTP/2 had segfault issues in early releases
- Node.js 20+: Stricter memory management exposed bugs in poorly-written addons
After major Node.js upgrades, always test thoroughly with native modules.
Monitoring for Segfaults in Production
In production, segfaults are hard to debug because they crash with no warning. Use monitoring:
import segfaultHandler from 'segfault-handler';
import fs from 'fs';
segfaultHandler.registerHandler('/var/log/app-crash.log');
// Log process state before crash
setInterval(() => {
console.log(`App running at ${new Date().toISOString()}`);
}, 60000);This at least records what your app was doing before the crash.
Error: EMFILE: too many open files, watch
EMFILE: fs.watch() limit exceeded
Error: Listener already called (once event already fired)
EventEmitter listener already called with once()
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