Mastering Node.js Error Handling: Strategies, Types, and Best Practices

Many developers overlook error handling, yet it is crucial for building robust Node.js applications.

Key questions include which method to expose errors ( throw, callback(err, result), EventEmitter), how to validate function parameters, how to handle unexpected parameters, how to distinguish error types (e.g., Bad Request, Service Unavailable), how to provide useful error information, and whether to capture errors with try/catch, domains, or other mechanisms.

Basic Knowledge

Ways to throw errors:

Ways to capture errors:

Classifying Errors

Generally, errors fall into two categories: operational errors and coding errors (bugs).

Experienced developers handle common operational errors such as JSON.parse failures or network issues with try...catch, treating them as non‑bugs.

Coding errors include undefined property reads, missing callbacks, or passing a String where an Object is expected. These are true bugs that must be fixed.

Sometimes the same symptom can be both an operational error (e.g., ECONNRESET from a server crash) and a coding error, depending on context.

How to Handle Operational Errors

1. For known operational error types, handle them directly (e.g., create a missing log file when ENOENT occurs).

2. For unexpected errors, log the error and let the process crash, providing appropriate information to the client.

How to Handle Coding Errors

The best approach is to let the process crash immediately, as these are bugs. Node.js processes are usually monitored and automatically restarted.

When an uncaughtException occurs, record relevant details for debugging.

Server‑side coding errors become operational errors for the client (e.g., a 500 response from an uncaught exception).

How to Propagate Errors?

Documentation is essential: describe function behavior, expected parameters, return values, and possible errors.

Guidelines:

In synchronous functions, use throw and let callers handle it with try...catch.

In asynchronous functions, prefer the callback(err, result) pattern.

For more complex scenarios, return an EventEmitter and emit an error event that callers can listen to.

Choose one error‑propagation method per function to avoid mixing patterns.

Is Invalid Input a Coding Error or an Operational Error?

If the input type does not match the function’s declared contract, it is a coding error; the caller should provide correct arguments.

If the input type matches but the function cannot process it, it is an operational error.

When to Use domain and process.on('uncaughtException') ?

Operational errors can usually be handled with explicit mechanisms ( try...catch, callbacks, or EventEmitters). Domains and global exception handlers are intended for unexpected coding errors.

Specific Recommendations for Writing Functions

Clearly define the function’s purpose, expected parameters, types, and constraints (e.g., IP address, QQ number). Throw an exception immediately if any requirement is violated.

Always use Error objects (or subclasses) with name, message, and a useful stack trace.

Use the name property to distinguish error types (e.g., RangeError, TypeError). For custom validation errors, a generic InvalidArgumentError with detailed messages is sufficient.

Add extra properties to provide context (e.g., remoteIp for connection failures).

When propagating lower‑level errors, consider wrapping them while preserving the original name and stack.

Use libraries such as node-verror to combine multiple errors.

Summary

Distinguish error types: predictable operational errors vs. unavoidable bugs.

Handle operational errors; let coding errors be logged globally and cause a crash.

Expose errors using either throw (synchronous) or a single asynchronous mechanism (callback or EventEmitter). In Node.js, asynchronous errors are more common.

Document function parameters, expected errors, and how to catch them.

Missing or invalid parameters are coding errors and should trigger throw.

Use the standard Error class and common property names (e.g., localHostname, remoteIp, path, errno).