Handling specific errors in JavaScript (think exceptions)

How would you implement different types of errors, so you'd be able to catch specific ones and let others bubble up..?

One way to achieve this is to modify the prototype of the Error object:

Error.prototype.sender = "";


function throwSpecificError()
{
    var e = new Error();
        
    e.sender = "specific";
    
    throw e;
}

Catch specific error:

try
{
    throwSpecificError();
}

catch (e)
{
    if (e.sender !== "specific") throw e;

    // handle specific error
}

Have you guys got any alternatives?

To create custom exceptions, you can inherit from the Error object:

function SpecificError () {

}

SpecificError.prototype = new Error();

// ...
try {
  throw new SpecificError;
} catch (e) {
  if (e instanceof SpecificError) {
   // specific error
  } else {
  	throw e; // let others bubble up
  }
}

A minimalistic approach, without inheriting from Error, could be throwing a simple object having a name and a message properties:

function throwSpecificError() {
  throw {
    name: 'SpecificError',
    message: 'SpecificError occurred!'
  };
}


// ...
try {
  throwSpecificError();
} catch (e) {
  if (e.name == 'SpecificError') {
   // specific error
  } else {
  	throw e; // let others bubble up
  }
}

As noted in the comments below this is Mozilla specific, but you can use 'conditional catch' blocks. e.g.:

try {
  ...
  throwSpecificError();
  ...
}
catch (e if e.sender === "specific") {
  specificHandler(e);
}
catch (e if e.sender === "unspecific") {
  unspecificHandler(e);
}
catch (e) {
  // don't know what to do
  throw e;
} 

This gives something more akin to typed exception handling used in Java, at least syntactically.

try-catch-finally.js

Using try-catch-finally.js, you can call the _try function with an anonymous callback, which it will call, and you can chain .catch calls to catch specific errors, and a .finally call to execute either way.

Example

_try(function () {
    throw 'My error';
})
.catch(Error, function (e) {
    console.log('Caught Error: ' + e);
})
.catch(String, function (e) {
    console.log('Caught String: ' + e);
})
.catch(function (e) {
    console.log('Caught other: ' + e);
})
.finally(function () {
    console.log('Error was caught explicitly');
});

Example with modern arrow functions and template literals

_try(() => {
  throw 'My error';
}).catch(Error, e => {
  console.log(`Caught Error: ${e}`);
}).catch(String, e => {
  console.log(`Caught String: ${e}`);
}).catch(e => {
  console.log(`Caught other: ${e}`);
}).finally(() => {
  console.log('Error was caught explicitly');
});

There is unfortunately no "official" way to achieve this basic functionality in Javascript. I'll share the three most common solutions I've seen in different packages, and how to implement them in modern Javascript (es6+), along with some of their pros and cons.

1. Subclass the Error class

Subclassing an instance of "Error" has become much easier in es6. Just do the following:

class FileNotFoundException extends Error {
  constructor(message) {
    super(message)
    // Not required, but makes uncaught error messages nicer.
    this.name = 'FileNotFoundException'
  }
}

Complete example:

class FileNotFoundException extends Error {
  constructor(message) {
    super(message)
    // Not required, but makes uncaught error messages nicer.
    this.name = 'FileNotFoundException'
  }
}

// Example usage

function readFile(path) {
  throw new FileNotFoundException(`The file ${path} was not found`)
}

try {
  readFile('./example.txt')
} catch (err) {
  if (err instanceof FileNotFoundException) {
    // Handle the custom exception
    console.log(`Could not find the file. Reason: ${err.message}`)
  } else {
    // Rethrow it - we don't know how to handle it
    // The stacktrace won't be changed, because
    // that information is attached to the error
    // object when it's first constructed.
    throw err
  }
}

If you don't like setting this.name to a hard-coded string, you can instead set it to this.constructor.name, which will give the name of your class. This has the advantage that any subclasses of your custom exception wouldn't need to also update this.name, as this.constructor.name will be the name of the subclass.

Subclassed exceptions have the advantage that they can provide better editor support (such as autocomplete) compared to some of the alternative solutions. You can easily add custom behavior to a specific exception type, such as additional functions, alternative constructor parameters, etc. It also tends to be easier to support typescript when providing custom behavior or data.

There's a lot of discussion about how to properly subclass Error out there. For example, the above solution might not work if you're using a transpiler. Some recommend using the platform-specific captureStackTrace() if it's available (I didn't notice any difference in the error when I used it though - maybe it's not as relevant anymore 路‍♂️). To read up more, see this MDN page and This Stackoverflow answer.

Many browser APIs go this route and throw custom exceptions (as can be seen here)

Note that babel doesn't support this solution very well. They had to make certain trade-offs when transpiling class syntax (because it's impossible to transpile them with 100% accuracy), and they chose to make instanceof checks broken on babel-transpiled classes. Some tools, like TypeScript, will indirectly use babel, and will thus suffer from the same issues depending on how you've configured your TypeScript setup. If you run this in TypeScript's playground with its default settings today (March 2022), it will log "false":

class MyError extends Error {}
console.log(MyError instanceof Error)

2. Adding a distinguishing property to the Error

The idea is really simple. Create your error, add an extra property such as "code" to your error, then throw it.

const error = new Error(`The file ${path} was not found`)
error.code = 'NotFound'
throw error

Complete example:

function readFile(path) {
  const error = new Error(`The file ${path} was not found`)
  error.code = 'NotFound'
  throw error
}

try {
  readFile('./example.txt')
} catch (err) {
  if (err.code === 'NotFound') {
    console.log(`Could not find the file. Reason: ${err.message}`)
  } else {
    throw err
  }
}

You can, of course, make a helper function to remove some of the boilerplate and ensure consistency.

This solution has the advantage that you don't need to export a list of all possible exceptions your package may throw. You can imagine how awkward that can get if, for example, your package had been using a NotFound exception to indicate that a particular function was unable to find the intended resource. You want to add an addUserToGroup() function that ideally would throw a UserNotFound or GroupNotFound exception depending on which resource wasn't found. With subclassed exceptions, you'll be left with a sticky decision to make. With codes on an error object, you can just do it.

This is the route node's fs module takes to exceptions. If you're trying to read a non-existent file, it'll throw an instance of error with some additional properties, such as code, which it'll set to "ENOENT" for that specific exception.

3. Return your exception.

Who says you have to throw them? In some scenarios, it might make the most sense to just return what went wrong.

function readFile(path) {
  if (itFailed()) {
    return { exCode: 'NotFound' }
  } else {
    return { data: 'Contents of file' }
  }
}

When dealing with a lot of exceptions, a solution such as this could make the most sense. It's simple to do, and can help self-document which functions give which exceptions, which makes for much more robust code. The downside is that it can add a lot of bloat to your code.

complete example:

function readFile(path) {
  if (Math.random() > 0.5) {
    return { exCode: 'NotFound' }
  } else {
    return { data: 'Contents of file' }
  }
}

function main() {
  const { data, exCode } = readFile('./example.txt')

  if (exCode === 'NotFound') {
    console.log('Could not find the file.')
    return
  } else if (exCode) {
    // We don't know how to handle this exCode, so throw an error
    throw new Error(`Unhandled exception when reading file: ${exCode}`)
  }

  console.log(`Contents of file: ${data}`)
}
main()

A non-solution

Some of these solutions feel like a lot of work. It's tempting to just throw an object literal, e.g. throw { code: 'NotFound' }. Don't do this! Stack trace information gets attached to error objects. If one of these object literals ever slips through and becomes an uncaught exception, you won't have a stacktrace to know where or how it happened. Debugging in general will be much more difficult. Some browsers may show a stacktrace in the console if one of these objects go uncaught, but this is just an optional convinience they provide, not all platforms provide this convinience, and it's not always accurate, e.g. if this object got caught and rethrown the browser will likely give the wrong stacktrace.

Bonus: Explicit Exceptions

When your package starts dealing with a lot of exceptions, I would recommend using the "return exception" method as described above, to help you keep track of which exceptions can come from where (at least use it internally within your package - you can still throw things for your package users). Sometimes even that solution is not good enough. I put together a little explicit-exceptions package to help in these scenarios (as can be found here. There's also a light version that you can just copy-paste into your project here). The idea is to require users to explicitly list which exceptions they expect a function call to provide. This makes it very easy to follow the path of an exception.

try {
  // readFile() will give an exception.
  // In unwrap(), you list which exceptions you except, to help with self-documentation.
  // runtime checks help ensure no other kinds of exceptions slip through.
  return unwrap(readFile('./example.txt'), ['NotFound'])
} catch (err) {
  // Handle the exception here
}

Complete example:

// You must have the explicit-exceptions package for this code to run
const { Exception, wrap, unwrap } = require('explicit-exceptions')

const readFile = wrap(path => {
  throw new Exception('NotFound')
})

function main () {
  try {
    return unwrap(readFile('./example.txt'), ['NotFound'])
  } catch (ex) {
    if (!(ex instanceof Exception)) throw ex // Not an exception, don't handle it
    console.assert(ex.code === 'NotFound')
    console.log('File not found')
  }
}

main()

Module for export usage

/**
 * Custom InputError
 */
class InputError extends Error {
  /**
   * Create InputError
   * @param {String} message
   */
  constructor(message) {
    super(message);
    this.name = this.constructor.name;
    Error.captureStackTrace(this, this.constructor);
  }
}

/**
 * Custom AuthError
 */
class AuthError extends Error {
  /**
   * Create AuthError
   * @param {String} message
   */
  constructor(message) {
    super(message);
    this.name = this.constructor.name;
    Error.captureStackTrace(this, this.constructor);
  }
}

/**
 * Custom NotFoundError
 */
class NotFoundError extends Error {
  /**
   * Create NotFoundError
   * @param {String} message
   */
  constructor(message) {
    super(message);
    this.name = this.constructor.name;
    Error.captureStackTrace(this, this.constructor);
  }
}

module.exports = {
  InputError: InputError,
  AuthError: AuthError,
  NotFoundError: NotFoundError
};

Import into script:

const {InputError, AuthError, NotFoundError} = require(path.join(process.cwd(), 'lib', 'errors'));

Use:

function doTheCheck = () =>
  checkInputData().then(() => {
    return Promise.resolve();
  }).catch(err => {
    return Promise.reject(new InputError(err));
  });
};

Calling code external:

doTheCheck.then(() => {
  res.send('Ok');
}).catch(err => {
  if (err instanceof NotFoundError) {
    res.status(404).send('Not found');
  } else if (err instanceof AuthError) {
    res.status(301).send('Not allowed');
  } else if (err instanceof InputError) {
    res.status(400).send('Input invalid');
  } else {
    console.error(err.toString());
    res.status(500).send('Server error');
  }
});

An older question, but in modern JS (as of late 2021) we can do this with a switch on the error's prototype constructor in the catch block, simply matching it directly to any and all error classes we're interested in rather than doing instanceof checks, taking advantage of the fact that while instanceof will match entire hierarchies, identity checks don't:

import { SomeError } from "library-that-uses-errors":
import MyErrors from "./my-errors.js";

try {
  const thing = someThrowingFunction();
} catch (err) {
  switch (err.__proto__.constuctor) {
    // We can match against errors from libraries that throw custom errors:
    case (SomeError): ...

    // or our own code with Error subclasses:
    case (MyErrors.SOME_CLASS_THAT_EXTENDS_ERROR): ..

    // and of course, we can check for standard built-in JS errors:
    case (TypeError): ...

    // and finally, if we don't know what this is, we can just
    // throw it back and hope something else deals with it.
    default: throw err;
  }
}

(Of course, we could do this with an if/elseif/else too if switches are too "I hate having to use break everywhere", which is true for a lot of folks)

I didn't love any of these solutions so I made my own. The try-catch-finally.js is pretty cool except that if you forget one little underscore (_) before the try then the code will still run just fine, but nothing will get caught ever! Yuck.

CatchFilter

I added a CatchFilter in my code:

"use strict";

/**
 * This catches a specific error. If the error doesn't match the errorType class passed in, it is rethrown for a
 * different catch handler to handle.
 * @param errorType The class that should be caught
 * @param funcToCall The function to call if an error is thrown of this type
 * @return {Function} A function that can be given directly to the `.catch()` part of a promise.
 */
module.exports.catchOnly = function(errorType, funcToCall) {
  return (error) => {
    if(error instanceof errorType) {
      return funcToCall(error);
    } else {
      // Oops, it's not for us.
      throw error;
    }
  };
};

Now I can filter

Now I can filter like in C# or Java:

new Promise((resolve, reject => {
   <snip><snip>
}).catch(CatchFilter.catchOnly(MyError, err =>
   console.log("This is for my error");
}).catch(err => {
   console.log("This is for all of the other errors.");
});