Node.js is widely loved for its asynchronous, event-driven architecture, enabling developers to build highly scalable network applications. However, this same asynchronous paradigm, combined with Node's single-threaded nature, makes error handling and debugging unique challenges.
When a Node.js process encounters an unhandled exception, it doesn't just fail silently—it exits, taking the entire server down with it. In this guide, we explore the most critical Node.js system and network errors, analyzing how to read stack traces, isolate root causes, and write defensive code to keep your processes alive.
Category 1: System & File System Errors (1–10)
These errors occur when the Node.js process interacts with the host operating system, local disk storage, or file system permissions.
- ENOENT (No Such File or Directory): Triggered when a file or folder operation is requested on a path that does not exist.
- EACCES (Permission Denied): Raised when attempting to access a file, directory, or socket without appropriate system permissions (e.g., trying to bind a server to port 80 without root access).
- EPERM (Operation Not Permitted): Occurs when an operation is blocked by the OS due to permissions or lock ownership (common when editing system files).
- EISDIR (Is a Directory): Raised when a file-only operation (like read or write) is attempted on a path that is actually a directory.
- ENOTDIR (Not a Directory): Occurs when a directory operation is attempted on a path that is actually a file.
- EEXIST (File Exists): Triggered when attempting to create a file or directory at a path where a resource already exists.
- EMFILE (Too Many Open Files): The operating system has run out of file descriptors for the Node process. Usually occurs when files or sockets are opened in loops without being closed.
- ENOSPC (No Space Left on Device): The disk is full, preventing any write operations.
- EROFS (Read-only File System): Occurs when attempting a write, delete, or modify operation on a read-only disk partition.
- ENOTEMPTY (Directory Not Empty): Triggered when trying to delete a folder using a non-recursive delete operation while files are still inside.
Category 2: Network & Socket Errors (11–20)
Network errors happen when Node services attempt to communicate with external APIs, databases, or local listening sockets.
- EADDRINUSE (Address Already in Use): Raised when attempting to bind an HTTP server to a local port that is already in use by another running process.
- ECONNRESET (Connection Reset by Peer): The active socket connection was abruptly terminated by the remote gateway or host.
- ECONNREFUSED (Connection Refused): The target server port rejected the connection, typically because the target database or server is offline.
- ETIMEDOUT (Connection Timeout): The outbound network request took too long to connect or respond, exceeding the socket timeout parameter.
- ENOTFOUND (DNS Lookup Failed): The host system cannot resolve the target domain name to an IP address (common when offline or when using incorrect API base URLs).
- EHOSTUNREACH (Host Unreachable): The host operating system cannot find a route to the target server IP address.
- EPIPE (Broken Pipe): Triggered when trying to write data to a socket or pipe that has already been closed by the receiver.
- EALREADY (Connection Already in Progress): A connection attempt is already active on the same socket.
- EISCONN (Socket is Connected): The socket is already connected, making another connection attempt invalid.
- ENOTCONN (Socket is Not Connected): Attempting to read or write data to a socket before a connection is established.
Category 3: Module & Dependency Resolution Errors (21–30)
These errors crop up during module loading, bundle compilation, package installation, or dependency linking.
- MODULE_NOT_FOUND: CommonJS
require()fails to resolve the path or package name specified. - ERR_MODULE_NOT_FOUND: ES Module
importfails to resolve a file, usually because the relative path lacks the file extension (e.g..js). - ERR_REQUIRE_ESM: Triggered when using CommonJS
require()to load a package compiled as an ES Module. - ERR_UNKNOWN_FILE_EXTENSION: Node.js encountered a file extension it cannot compile or parse as JavaScript.
- ERR_INVALID_PACKAGE_TARGET: The package.json
exportsmapping configuration resolves to an invalid target directory. - ERR_INVALID_MODULE_SPECIFIER: The import path string contains invalid syntax or characters.
- ERR_PACKAGE_IMPORT_NOT_DEFINED: Attempted to import a private subpath helper that is not declared in the package.json imports map.
- ERR_PACKAGE_PATH_NOT_EXPORTED: A subpath within a dependency is private and cannot be loaded because it is not exposed in the library's exports configuration.
- ERR_AMBIGUOUS_EXPORT: A module has conflicting ES Module named exports, making resolution ambiguous.
- ERR_MISSING_MODULE: A native C++ binary module package (like bcrypt) is missing compilation files for the host architecture.
Category 4: V8 Engine & JavaScript runtime exceptions (31–40)
Exceptions thrown directly by the V8 JavaScript engine during execution due to syntax violations or runtime constraints.
- TypeError: An operation is performed on an incompatible data type (e.g. calling a property that is
undefined). - ReferenceError: Raised when attempting to reference a variable or function that has not been declared.
- RangeError: An argument or variable value falls outside its permitted numeric range (e.g. configuring invalid array lengths or triggers).
- SyntaxError: The JS code fails the initial compile-time parsing phase (e.g. missing brackets or commas).
- URIError: Encoutered when passing invalid URI characters to global functions like
decodeURI(). - ERR_ASSERTION: Raised by the Node assert module when a test check evaluates to false.
- ERR_INVALID_ARG_TYPE: An API parameter is passed with an incorrect JavaScript type.
- ERR_OUT_OF_RANGE: A numeric value exceeds the range limits of a configuration parameter.
- ERR_BUFFER_OUT_OF_BOUNDS: Attempted to read or write binary values outside the boundaries of a allocated Buffer.
- JavaScript Heap Out of Memory: The V8 engine has reached its maximum memory allocation heap size limit, causing the process to crash.
Category 5: Asynchronous Flow & Stream Errors (41–50)
Errors related to async callbacks, promise rejections, streaming pipelines, and HTTP transaction lifecycle events.
- UnhandledPromiseRejection: A promise is rejected but has no catch handler, leading to runtime exit.
- ERR_UNHANDLED_ERROR: An EventEmitter instance emits an
'error'event but has no listener registers configured. - ERR_STREAM_PREMATURE_CLOSE: A stream pipe operation terminated abruptly before all binary packets were fully flushed.
- ERR_STREAM_WRITE_AFTER_END: Attempted to write buffer chunks to a stream that has already ended or closed.
- ERR_STREAM_DESTROYED: Attempted to interact with a stream after it was destroyed by an error event.
- ERR_HTTP_HEADERS_SENT: Triggered when a controller attempts to set HTTP response headers or status codes after sending body payloads to the client.
- ERR_HTTP_INVALID_STATUS_CODE: Setting a response status code integer outside the valid range of 100 to 999.
- ERR_HTTP2_INVALID_STREAM: Encountered a protocol violation in an active HTTP/2 socket connection stream.
- ERR_CHILD_PROCESS_IPC_DISCONNECTED: The IPC communication channel between parent and child cluster processes was closed.
- ERR_WORKER_OUT_OF_MEMORY: A multi-threaded worker thread exceeded its local heap memory limits, forcing termination.
Summary Checklist for Resilient Node.js Coding
To protect your applications from crashes across all 50 error vectors, practice these core coding paradigms:
- Always wrap asynchronous function calls in robust try/catch blocks.
- Listen to process-wide signals (
uncaughtExceptionandunhandledRejection) to log crash contexts. - Use stream helpers like
pipeline()instead of raw.pipe()to catch stream closures safely. - Monitor memory heaps using APM tools to catch memory leaks before the process hits OOM limits.