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

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

Key Questions

Which mechanism should be used to expose errors? throw, callback(err, result), EventEmitter, or others?

How should function arguments be assumed? Should type checking be performed?

How to handle arguments that do not meet expectations?

How to differentiate error types such as Bad Request vs Service Unavailable?

How to provide useful error information?

How to capture errors? Use try/catch, domains, or other methods?

Fundamental Concepts

References for Error, throw, and try...catch are available on MDN. Node.js v7.2.0 introduces domain and process APIs. The verror module offers rich JavaScript errors.

Ways to Throw Errors

var myEmitter = new MyEmitter();
doSomeAsynchronousOperation(function (err) {
    if (err) throw err; // direct throw
    if (err) callback(err); // callback style
    myEmitter.emit('error', new Error('whoops!')); // EventEmitter error
});

Catching Errors

try {
    var result = JSON.parse(str);
} catch (e) {
    // handle error
}

Classifying Errors

Errors are generally divided into operational errors and coding errors (bugs). Operational errors, such as network failures or a missing file, are expected and should be handled. Coding errors, like accessing an undefined property or passing an argument of the wrong type, indicate bugs and should not be recovered from.

Handling Operational Errors

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

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

Handling Coding Errors

The best approach is to let the process crash immediately, record the uncaught exception, and rely on a process manager to restart the service.

How to Propagate Errors

Documentation should clearly describe a function’s purpose, expected parameters, and possible errors.

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

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

For more complex scenarios, return an EventEmitter and emit an error event.

Choose the mechanism based on whether the error is operational or a coding error, and whether the function is synchronous or asynchronous. Use a single error‑handling strategy per function.

Designing Functions

Clearly define expected arguments, types, and constraints.

Throw throw immediately when any expectation is violated.

Expose only Error objects (or subclasses) with name, message, and a useful stack.

Use the name property to distinguish error categories (e.g., RangeError, TypeError).

Provide additional properties (e.g., remoteIp) for richer context.

When re‑throwing lower‑level errors, wrap them while preserving the original error object.

Summary

Distinguish between operational errors (handle) and coding errors (record and crash).

Use a single error‑handling approach per function: throw for sync, callback or EventEmitter for async.

Document function contracts, expected errors, and how to capture them.

All errors should be instances of Error with standard properties and optional custom fields.

Final Tips

Never use try...catch to capture asynchronous errors.

Only throw when an error actually occurs.

Historical concepts of operational vs coding errors are discussed in software assertions.