Node.js Best Practice Exception Handling

Question

I just started trying out node.js a few days ago. I've realized that the Node is terminated whenever I have an unhandled exception in my program. This is different than the normal server container that I have been exposed to where only the Worker Thread dies when unhandled exceptions occur and the container would still be able to receive the request. This raises a few questions:

Is process.on('uncaughtException') the only effective way to guard against it?
Will process.on('uncaughtException') catch the unhandled exception during execution of asynchronous processes as well?
Is there a module that is already built (such as sending email or writing to a file) that I could leverage in the case of uncaught exceptions?

I would appreciate any pointer/article that would show me the common best practices for handling uncaught exceptions in node.js

uncaught exceptions should not happen. If they do use a program that restarts your entire application when its crashing (nodemon, forever, supervisor) — Raynos
Uncaught exceptions can always happen unless you put every piece of your asynchronous code inside try .. catch, and check this is also done for all your libs — Dan
+1 Dan At first I thought all your libs was a bit of an exaggeration, as you "only" need to wrap all your "thread entry points" in the code in try/catches. But thinking about it more carefully, any lib could have a setTimeout or setInterval or something of that kind buried somewhere deep which cannot be caught by your code. — Evgeniy Berezovsky
@EugeneBeresovksy Dan is right but it doesn't change the fact that when uncaughtExceptions occur the only safe option is to restart the app. In other words your app has crashed and there's nothing you can do or should do about it. If you want to do something constructive implement the new, and still experimental, v0.8 domain feature so you can log the crash and send a 5xx response to your client. — ostergaard
@Dan Even enclosing all callback functions in try .. catch doesn't guarantee catching errors. In the case that a required module uses it's own binaries they can crash ungracefully. I've had this happen with phantomjs-node, failing on errors that are impossible to catch (unless I was to do some kind of process inspection on required binaries, but I never pursued that). — Trindaz

balupton balupton · Accepted Answer · 2011-09-05T21:45:12

Update: Joyent now has their own guide. The following information is more of a summary:

Safely "throwing" errors

Ideally we'd like to avoid uncaught errors as much as possible, as such, instead of literally throwing the error, we can instead safely "throw" the error using one of the following methods depending on our code architecture:

For synchronous code, if an error happens, return the error:

// Define divider as a syncrhonous function
var divideSync = function(x,y) {
    // if error condition?
    if ( y === 0 ) {
        // "throw" the error safely by returning it
        return new Error("Can't divide by zero")
    }
    else {
        // no error occured, continue on
        return x/y
    }
}

// Divide 4/2
var result = divideSync(4,2)
// did an error occur?
if ( result instanceof Error ) {
    // handle the error safely
    console.log('4/2=err', result)
}
else {
    // no error occured, continue on
    console.log('4/2='+result)
}

// Divide 4/0
result = divideSync(4,0)
// did an error occur?
if ( result instanceof Error ) {
    // handle the error safely
    console.log('4/0=err', result)
}
else {
    // no error occured, continue on
    console.log('4/0='+result)
}

For callback-based (ie. asynchronous) code, the first argument of the callback is err, if an error happens err is the error, if an error doesn't happen then err is null. Any other arguments follow the err argument:

var divide = function(x,y,next) {
    // if error condition?
    if ( y === 0 ) {
        // "throw" the error safely by calling the completion callback
        // with the first argument being the error
        next(new Error("Can't divide by zero"))
    }
    else {
        // no error occured, continue on
        next(null, x/y)
    }
}

divide(4,2,function(err,result){
    // did an error occur?
    if ( err ) {
        // handle the error safely
        console.log('4/2=err', err)
    }
    else {
        // no error occured, continue on
        console.log('4/2='+result)
    }
})

divide(4,0,function(err,result){
    // did an error occur?
    if ( err ) {
        // handle the error safely
        console.log('4/0=err', err)
    }
    else {
        // no error occured, continue on
        console.log('4/0='+result)
    }
})

For eventful code, where the error may happen anywhere, instead of throwing the error, fire the error event instead:

// Definite our Divider Event Emitter
var events = require('events')
var Divider = function(){
    events.EventEmitter.call(this)
}
require('util').inherits(Divider, events.EventEmitter)

// Add the divide function
Divider.prototype.divide = function(x,y){
    // if error condition?
    if ( y === 0 ) {
        // "throw" the error safely by emitting it
        var err = new Error("Can't divide by zero")
        this.emit('error', err)
    }
    else {
        // no error occured, continue on
        this.emit('divided', x, y, x/y)
    }

    // Chain
    return this;
}

// Create our divider and listen for errors
var divider = new Divider()
divider.on('error', function(err){
    // handle the error safely
    console.log(err)
})
divider.on('divided', function(x,y,result){
    console.log(x+'/'+y+'='+result)
})

// Divide
divider.divide(4,2).divide(4,0)

Safely "catching" errors

Sometimes though, there may still be code that throws an error somewhere which can lead to an uncaught exception and a potential crash of our application if we don't catch it safely. Depending on our code architecture we can use one of the following methods to catch it:

When we know where the error is occurring, we can wrap that section in a node.js domain

var d = require('domain').create()
d.on('error', function(err){
    // handle the error safely
    console.log(err)
})

// catch the uncaught errors in this asynchronous or synchronous code block
d.run(function(){
    // the asynchronous or synchronous code that we want to catch thrown errors on
    var err = new Error('example')
    throw err
})

If we know where the error is occurring is synchronous code, and for whatever reason can't use domains (perhaps old version of node), we can use the try catch statement:

// catch the uncaught errors in this synchronous code block
// try catch statements only work on synchronous code
try {
    // the synchronous code that we want to catch thrown errors on
    var err = new Error('example')
    throw err
} catch (err) {
    // handle the error safely
    console.log(err)
}

However, be careful not to use try...catch in asynchronous code, as an asynchronously thrown error will not be caught:

try {
    setTimeout(function(){
        var err = new Error('example')
        throw err
    }, 1000)
}
catch (err) {
    // Example error won't be caught here... crashing our app
    // hence the need for domains
}

If you do want to work with try..catch in conjunction with asynchronous code, when running Node 7.4 or higher you can use async/await natively to write your asynchronous functions.

Another thing to be careful about with try...catch is the risk of wrapping your completion callback inside the try statement like so:

var divide = function(x,y,next) {
    // if error condition?
    if ( y === 0 ) {
        // "throw" the error safely by calling the completion callback
        // with the first argument being the error
        next(new Error("Can't divide by zero"))
    }
    else {
        // no error occured, continue on
        next(null, x/y)
    }
}

var continueElsewhere = function(err, result){
        throw new Error('elsewhere has failed')
}

try {
        divide(4, 2, continueElsewhere)
        // ^ the execution of divide, and the execution of 
        //   continueElsewhere will be inside the try statement
}
catch (err) {
        console.log(err.stack)
        // ^ will output the "unexpected" result of: elsewhere has failed
}

This gotcha is very easy to do as your code becomes more complex. As such, it is best to either use domains or to return errors to avoid (1) uncaught exceptions in asynchronous code (2) the try catch catching execution that you don't want it to. In languages that allow for proper threading instead of JavaScript's asynchronous event-machine style, this is less of an issue.

Finally, in the case where an uncaught error happens in a place that wasn't wrapped in a domain or a try catch statement, we can make our application not crash by using the uncaughtException listener (however doing so can put the application in an unknown state):

// catch the uncaught errors that weren't wrapped in a domain or try catch statement
// do not use this in modules, but only in applications, as otherwise we could have multiple of these bound
process.on('uncaughtException', function(err) {
    // handle the error safely
    console.log(err)
})

// the asynchronous or synchronous code that emits the otherwise uncaught error
var err = new Error('example')
throw err

Node.js Best Practice Exception Handling

11 Answers

Safely "throwing" errors

Safely "catching" errors

Best practices of Node.JS error handling

Number1: Use promises for async error handling

Number2: Use only the built-in Error object

Number3: Distinguish operational vs programmer errors

Number4: Handle errors centrally, through but not within middleware

Number5: Document API errors using Swagger

Number6: Shut the process gracefully when a stranger comes to town

Number7: Use a mature logger to increase errors visibility

Number8: Discover errors and downtime using APM products