The previous lesson in this module finished a batch of requests, and it showed you how to wait for several promises at once. That is a good place to stop and look at what happens when something goes wrong instead of what happens when everything works. Error handling in JavaScript comes down to one decision that you make before any code runs, and that decision is about which failures are part of normal operation and which ones mean that your program has a bug. The first kind deserves a friendly message and a sensible fallback. The second kind deserves a stack trace and a fix.
This is the first lesson in the JavaScript Error Handling and a Capstone Project module, and the next lesson in this module is about "Organizing a Script Without a Framework".
What kinds of failure does a larger script have to survive?
A script that handles one file and prints one line does not need an error strategy at all. A script that reads configuration, calls a service, and writes results has at least four kinds of failure to think about, and each of them calls for a different reaction.
| Failure | Example | How to react |
|---|---|---|
| Bad input | a port number that is not a number | Reject it and say which field was wrong |
| Missing resource | a config file that is not on disk | Fall back to a default and carry on |
| A dependency failed | a request came back with a server error | Retry, degrade, or report the failure |
| A bug in your code | reading a property of something that is not there | Let it surface, then fix the code |
Most scripts that feel fragile are not missing a catch block. They have one catch block that treats every failure in exactly the same way, so a small typo in the middle of a function is reported to the user as a network problem.
How do you tell an expected failure apart from a bug?
You give the expected failures their own error type. If your own code throws a named error class, then the catch block can look at what it caught and react differently to "no such record" and to "you passed a string where a number was expected".
class NotFoundError extends Error {
constructor(id) {
super('no record with id ' + id);
this.name = 'NotFoundError';
this.id = id;
}
}
function parseId(raw) {
const id = Number(raw);
if (!Number.isInteger(id)) {
throw new TypeError('id must be a whole number, got: ' + raw);
}
return id;
}
async function loadRecord(id) {
if (id === 99) {
throw new NotFoundError(id);
}
return { id: id, name: 'record ' + id };
}
async function show(raw) {
try {
const id = parseId(raw);
const record = await loadRecord(id);
console.log('loaded', record.name);
} catch (error) {
if (error instanceof NotFoundError) {
console.log('nothing to show:', error.message);
return;
}
console.log('unexpected failure:', error.message);
}
}
show('7');
show('99');
show('seven');
The output shows all three calls being handled by the same catch block, but not being treated in the same way:
unexpected failure: id must be a whole number, got: seven
loaded record 7
nothing to show: no record with id 99
The broken input is reported first because it fails before the first await, so its message is printed while the other two calls are still waiting for their promises. Output that arrives in an order like that surprises people once, and then they stop reading the output as a sequence.
Notice what the catch block did with the two cases. A missing record is an ordinary outcome, so the function returns quietly. A programming mistake gets its own line, so it stays visible instead of being swallowed into a friendly message.
Why does a custom error class beat a thrown string?
Because a class carries structured information. It has a name, it can hold extra fields, and the catch block can test it with instanceof. A thrown string gives you nothing but text, so every catch block has to compare text to work out what actually happened.
class ValidationError extends Error {
constructor(field, message) {
super(message);
this.name = 'ValidationError';
this.field = field;
}
}
function createAccount(email, age) {
if (!email.includes('@')) {
throw new ValidationError('email', 'needs an @ sign');
}
if (age < 13) {
throw new ValidationError('age', 'must be at least 13');
}
return { email: email, age: age, id: 'acc_' + email.length };
}
try {
createAccount('adaexample.com', 20);
} catch (error) {
console.log(error.name, '->', error.field + ':', error.message);
}
The output is:
ValidationError -> email: needs an @ sign
The field property is the part that pays off in a real application. A form can point at the offending input, a log line can be grouped by field, and a test can check the field without parsing the message text.
Setting name on the class matters too, because that is what shows up in a log line and what tells you which class of problem you are looking at.
Where should the catch block live?
As close to the failure as possible when the failure is expected and local, and as far away as possible when it is not. The inner functions should throw, and the outer layer should decide what happens. A function that swallows an error deep inside a chain leaves nobody able to tell whether the data was missing or the logic was wrong.
async function readText(path) {
if (path !== 'app.json') {
throw new Error('config not found: ' + path);
}
return '{"port": 8080}';
}
async function loadConfig(path) {
const text = await readText(path);
return JSON.parse(text);
}
async function run() {
try {
const config = await loadConfig('app.json');
console.log('starting on port', config.port);
} catch (error) {
console.error('fatal:', error.message);
}
}
run();
The output for a good run is:
starting on port 8080
Neither readText nor loadConfig catches anything. They throw, and the single catch block at the top of run decides what the program does about it. Point the call at a missing file and the same block reports the failure instead.
When is a result object better than an exception?
Exceptions are for the exceptional. When a failure is an ordinary answer to a question, such as "is this a valid port number", returning a small object is often clearer than throwing, because the caller cannot forget to handle it.
function parsePort(raw) {
const port = Number(raw);
if (!Number.isInteger(port) || port < 0 || port > 65535) {
return { ok: false, error: 'not a valid port: ' + raw };
}
return { ok: true, value: port };
}
const good = parsePort('8080');
console.log(good.ok ? 'using port ' + good.value : good.error);
const bad = parsePort('http');
console.log(bad.ok ? 'using port ' + bad.value : bad.error);
The output is:
using port 8080
not a valid port: http
The two approaches trade places depending on the situation:
| Situation | Use a thrown error | Use a result object |
|---|---|---|
| How often it happens | Rare | Common |
| Who reacts | A catch block further up | The caller, right there |
| Readability | Happy path stays clean | Every caller checks a flag |
| Good fit | A file that could not be read | Validating one field of a form |
A useful middle ground is a thrown error for anything the caller cannot possibly handle, and a result object for the validations that happen on every single request.
How should a script report a failure to whoever ran it?
Three habits cover most of it. Send normal output to standard output and failures to standard error, so that the two can be separated in a pipeline. Put the message first and the detail after it, so that the first line of a log is the useful part. And give the process a failing exit status when it failed, so that a script which runs on a schedule or inside a pipeline can be monitored without anybody reading the output.
The run function above already does the first two of those habits. It prints the ordinary line with console.log, and it prints the failure with console.error. When a script runs inside a browser instead of a terminal, those two habits are the ones that apply, and the third one becomes a state on your page that you can display to the user.
An error-handling checklist for larger scripts
- Decide up front which failures are ordinary and which ones are bugs, and never mix the two in one catch block.
- Give the expected failures their own error class, so that the catch block can tell them apart with
instanceof. - Let the low-level functions throw, and handle the failures at the layer that knows what to do about them.
- Use result objects for validation that happens on every call, and exceptions for the rare path.
- Include the field or the record in the message, so that the person reading it knows what to fix.
- Report failures on standard error, so that automation can react to them.
- Never end a catch block with nothing in it. Log it, re-throw it, or return a deliberate fallback.
Try it yourself: Write a function parseSettings(raw) that reads a JSON string and returns a result object with ok, and either a value or an error that explains which setting is wrong. Then write a wrapper loadSettings(path) that throws a typed error when the file is missing and returns the parsed object in every other case. Call the wrapper inside a try/catch block that prints a different message for a missing file and for a bad value. Run it once with valid input, once with a file that does not exist, and once with a file that contains invalid JSON, and check that all three cases produce a different and sensible line.
The next lesson in this module looks at how to organise a growing JavaScript project, so that the files you write here stay easy to find as the number of scripts grows.