Throwing, and the objects you throw

Every error so far came from the engine. You can throw too, and you should: the engine only knows about the rules of JavaScript, whereas you know about the rules of your program. JavaScript has no opinion on whether a volume of 12 is acceptable. You do.

The statement is throw, followed by the value. In practice that value should almost always be a fresh error object: throw new Error("..."), or one of the more specific types.

A thrown error is not caught by the function that threw it. It leaves immediately and becomes the caller's problem, and then the caller's caller's, until somebody handles it. Deciding where that somebody should be is lesson three; deciding what they receive is this lesson.

return hands a value back to the one place that called you, and that place carries on with the next line. throw hands a value back to whoever is prepared to catch it, and every line in between is abandoned.

That difference is why a throw cannot be ignored and a returned error code can. If a function returns the string "error" and the caller does not look at it, nothing happens and the program continues with a wrong value. If the same function throws, the caller either handles it or is stopped by it.

The cost of that guarantee is that throwing takes the decision away from the caller. That is right for a genuine mistake and wrong for an ordinary bad input, which is the subject of lesson five.

Invalid input is not a message. It tells the reader that something is wrong, which they already knew, and nothing else.

A message worth writing has three ingredients: where the failure was noticed, what was expected, and what actually arrived. createUser: name must be a non-empty string, received number 5 has all three. Someone reading it in a log at 2am knows which function to open, what the rule is, and what broke it, without running anything.

Include the received value, but be deliberate about it. A value is worth showing when it is small and safe: a number, a short string, a type name. Never paste an entire request body, and never paste anything you would not want written down permanently — a log file is a permanent copy of whatever you put in it, in a place with different access rules from the original.

TypeError: the value is the wrong kind of thing for the operation. A string where a number was needed, null where an object was needed.

RangeError: the value is the right kind of thing and outside what is allowed. A volume of 12 on a dial that goes to 11, a page number of zero, a percentage of 150.

Error: everything else — a rule of your program that was broken, where neither kind nor range is really the issue. A subclass of Error, covered next, is usually better than plain Error for anything that happens more than once.

Two types are best left to the engine. SyntaxError describes text that is not JavaScript or not JSON, and ReferenceError describes a name that does not exist; throwing either from your own code sends a reader hunting for a problem of a kind that is not there.

Sometimes the handler needs to do more than print. A form wants to know which field was wrong so it can highlight it, and reading that back out of an English sentence is not a plan.

Extend Error with a class, set this.name in the constructor, and add whatever fields the handler needs. The result is still a real error: instanceof Error is true, the message and stack still work, and any handler that only wants to print it can carry on doing exactly that.

When one failure is caused by another, keep the original. The Error constructor takes a second argument, an options object with a cause property: new Error("loadConfig failed", { cause: original }). The handler then has both the sentence that makes sense at this level and the underlying failure it came from, instead of one at the expense of the other.

throw "something broke" is legal. JavaScript lets you throw any value at all, and beginners reach for a string because it is shorter.

What arrives at the catch block is then a bare string. It has no name, so nothing can branch on the kind of failure. It has no stack, so nothing can say where it came from. error instanceof Error is false, so every defensive handler downstream — including ones written by other people — has to cope with a value that is not an error object.

The rule is simple and has no useful exceptions: throw errors, not values. The corresponding rule for catch is that you must nonetheless assume somebody else broke this rule, which is why lesson three checks what it caught.

JSON.stringify(new Error("boom")) produces {} — an empty object. The information is not lost from the error, but none of it is copied out.

There are two reasons. message is an own property but a non-enumerable one, and JSON.stringify only copies enumerable own properties. name is not an own property at all: it lives on Error.prototype, shared by every error of that type, and JSON.stringify never looks up the prototype chain.

So anything that sends an error somewhere else — a log line, a network message, a stored record — has to build the shape it wants by hand: { name: error.name, message: error.message }. Discovering this in production, with a log full of empty braces, is a rite of passage worth skipping.