Reading error messages

An error is a clue

Sometimes JavaScript reaches a line it cannot run. Then it stops and throws an error. That means it stops running your code and prints a report in the console, usually in red.

Red text can feel like "you failed". It is not. The report is a clue. It tells you what went wrong and where to look.

An error report has three parts:

• The name, like TypeError or ReferenceError. It tells you the kind of mistake.
• The message, like Cannot read properties of undefined. It tells you which step failed. The wording can differ from browser to browser.
• The stack trace. It is a list of the functions that were running, newest first. The top one is where the error happened.

You have already used the console, and you saw strict mode turn quiet mistakes into errors. This lesson teaches you to read those errors. The next lesson, Debugging in the browser, shows how to pause your code and look inside it.

You will meet three errors all the time. Each one answers a different question:

• SyntaxError: "Can JavaScript read this text?" Syntax means the grammar of the code, like brackets and commas.
• ReferenceError: "Does this name exist?"
• TypeError: "Can this value do this?"

A SyntaxError does not only come from your code file. JSON is a text format for data. It looks a lot like a JavaScript object. JSON.parse reads JSON text and turns it into a value. It reads the text while your program runs. So bad JSON text can throw a SyntaxError even after your code has started.

The table below has one row per error. Read each row as: "this name means this, and here is a tiny example."

A missing property and a missing name are not the same thing. A property is a named value inside an object. An object can exist without a total property. Reading a property that isn't there gives undefined. It does not throw.

1const cart = {};2console.log(cart.total);

Line 1 makes an empty object called cart. Line 2 reads its total property. There is none, so it prints undefined. This can cause an error later. For example, cart.total.price would try to read price from undefined, and that throws a TypeError.

A missing name is different. If no variable has the name, JavaScript cannot look it up at all, and it throws. The next example uses try and catch:

• JavaScript runs the code inside try.
• If that code throws, JavaScript jumps to catch. The error is handed in as error.
• error.name is the error's name, and error.message is its message.

A later lesson covers try and catch fully. Here they only let us print the error's name.

1try {2  console.log(total);3} catch (error) {4  console.log(error.name);5}

Line 2 uses total, but no variable has that name. So JavaScript throws, and jumps to catch. Line 4 prints the error's name: ReferenceError. Remember the difference: cart.total is a missing property, and gives undefined. total on its own is a missing name, and throws.

Now a variable that exists, but holds a value that cannot do the job. Line 1 stores undefined in user. Line 2 tries to read the name property of that value. undefined has no properties, so JavaScript throws a TypeError. The exact message depends on your browser.

1const user = undefined;2user.name;

Try each error in the lab below. Each button runs a small piece of code in your browser. The lab uses try and catch so it can show you error.name and error.message.

1const demos = {2  reference() {3    console.log(total);4  },5  type() {6    const user = undefined;7    return user.name;8  },9  range() {10    return new Array(-1);11  },12  uri() {13    return decodeURIComponent("%");14  },15  syntaxAtRuntime() {16    return JSON.parse("{bad json}");17  },18  evalCompatibility() {19    throw new EvalError("EvalError still exists");20  },21};22 23function inspectError(runDemo) {24  try {25    runDemo();26  } catch (error) {27    return {28      name: error.name,29      message: error.message,30    };31  }32}

Look at what stays the same. The name is the same in every browser. The message can be worded differently. Chrome and Node say Cannot read properties of undefined (reading 'name'). Firefox says it a different way. When a lesson shows an exact message, it says which browser it comes from.

So in a catch block, use error.name to check the kind of error. Read error.message as a helpful note for people. Don't write code that checks for one exact message, because another browser may word it differently.

1try {2  JSON.parse("{bad json}");3} catch (error) {4  console.log(error.name);5  console.log(typeof error.message);6}

Line 2 gives JSON.parse broken JSON text on purpose. It throws, and JavaScript jumps to catch. Line 4 prints SyntaxError. Line 5 uses typeof, which tells you what kind of value something is. It prints string, because the message is text. The example doesn't print the message itself, because its wording differs between browsers.

You will see the next three errors less often. Knowing them makes some scary messages easy to read.

One of them is about URIs. A URI is text that points to something, like a web address. Some characters can't go in a web address as they are, such as a space. So they are written as a code that starts with %. For example, a space is written %20. decodeURIComponent turns those codes back into normal text.

• RangeError means a number is too big or too small for the job. new Array(-1) throws, because an array (a list of values) can't have a length below zero. (1).toFixed(101) throws too. toFixed rounds a number to a set count of decimal places, and that count must be from 0 to 100. In Chrome and Node the message says toFixed() digits argument must be between 0 and 100.
• URIError means the % codes in the text are broken. % must be followed by a valid code. So decodeURIComponent("%") throws, with the message URI malformed. "Malformed" means "badly made".
• EvalError is an old error. JavaScript today does not throw it on its own. It still exists so that old code keeps working. Your own code can still make one with new EvalError("message").

Got a RangeError or a URIError? Try the same function with an input you know is valid. If that works, the function is fine, and only your input is wrong.

1console.log((12.5).toFixed(2));2console.log(decodeURIComponent("tea%20and%20toast"));

Line 1 asks for two decimal places. That is between 0 and 100, so it prints 12.50. Line 2 turns each %20 back into a space and prints tea and toast. Valid inputs, so nothing throws.

Now sort some real messages by error name. Some messages come from built-in functions like JSON.parse, not from your own code's grammar. So always look at the line that threw, too.

A stack trace is the list of function calls that were running when the error happened. It is printed under the message. The newest call is at the top. Each line of the list is called a frame.

• The top frame answers: "Where did the error happen?"
• Each frame below it answers: "Who called the one above?"

A frame usually gives a function name, a file name, and a place in that file: file:line:column. For example, cart.js:10:32 means file cart.js, line 10, character 32 on that line.

Step through this small checkout bug. The order has a total, but no discount. Watch the "Running in" list grow as each function calls the next one.

1function placeOrder(order) {2  return calculateTotal(order);3}4 5function calculateTotal(order) {6  return applyDiscount(order.total, order.discount);7}8 9function applyDiscount(total, discount) {10  return total * (1 - discount.rate);11}12 13placeOrder({ total: 40 });Run

Now see a real stack trace from your own browser. The error object keeps it as text in error.stack. Your browser may write it a bit differently. The steps stay the same: read the message, find the top frame in your code, then check the value that line used.

1function placeOrder(order) {2  return calculateTotal(order);3}4 5function calculateTotal(order) {6  return applyDiscount(order.total, order.discount);7}8 9function applyDiscount(total, discount) {10  return total * (1 - discount.rate);11}12 13placeOrder({ total: 40 });

TypeError: Cannot read properties of undefined (reading 'rate')
    at applyDiscount (cart.js:10:32)
    at calculateTotal (cart.js:6:10)
    at placeOrder (cart.js:2:10)
    at cart.js:13:1

Here is the same stack trace as Chrome and Node write it, with a note for each line. Chrome and Node both run JavaScript with the same engine, called V8. An engine is the part that runs your JavaScript. Firefox uses a different engine. It writes frames like applyDiscount@cart.js:10:32 instead.

1TypeError: Cannot read properties of undefined (reading 'rate')2    at applyDiscount (cart.js:10:32)3    at calculateTotal (cart.js:6:10)4    at placeOrder (cart.js:2:10)5    at cart.js:13:1

A web search can explain an error you have never seen. But the search works best with the right words. Error messages often contain your own names: your variables, your properties, your files. Nobody else uses those names. So keep the part of the message everyone sees, and leave out your own names.

1const account = undefined;2console.log(account.profile.name);

Line 1 stores undefined in account. Line 2 tries to read account.profile, so it throws a TypeError. In Chrome the message is Cannot read properties of undefined (reading 'profile'). The word profile is your own name. The rest is the same for everyone.

A good first search is "Cannot read properties of undefined", in quotes. Once you know what kind of error it is, go back to your code. Then ask the real question: "Why is this value undefined here?"

1const errorName = "TypeError";2const sharedMessage = "Cannot read properties of undefined";3console.log(errorName + ' "' + sharedMessage + '"');

Line 1 stores the error name. Line 2 stores the part of the message everyone sees, without your own names. Line 3 joins them, with the message in quotes. It prints TypeError "Cannot read properties of undefined".

A minimal reproduction is the smallest piece of code that still shows the same error. "Minimal" means as small as possible. "Reproduction" means it makes the error happen again. With less code around it, it is easier to see which value is wrong.

To make one:

1. Keep the line that fails, and the value it gets.
2. Remove one part that seems unrelated.
3. Run the code again.
4. If the error is still there, repeat. If the error is gone, the part you removed mattered. Put it back and remove a different part.

1function showProfileName(user) {2  return user.name;3}4 5showProfileName(undefined);

Line 1 starts a function that expects a user object. Line 2 reads the user's name. Line 5 calls the function with undefined instead of a user. So line 2 tries to read name from undefined, and throws a TypeError. The rest of the web page is not needed to show this bug.

Now change only the value passed in. The function stays the same. Line 5 makes a user object. Line 6 calls the function and prints the name it returns: Asha.

1function showProfileName(user) {2  return user.name;3}4 5const user = { name: "Asha" };6console.log(showProfileName(user));

Sometimes a missing user is normal. For example, a visitor who has not logged in has no profile. Then your code should show something sensible, like the word Guest. But if the profile should always be there, don't hide the problem. Find out why it is missing, and fix the code that passes it in.

1function profileLabel(user) {2  if (user === undefined || user === null) {3    return "Guest";4  }5  return user.name;6}7 8console.log(profileLabel(undefined));9console.log(profileLabel(null));10console.log(profileLabel({ name: "Asha" }));

Line 1 starts a function. Line 2 checks for a missing user: is it undefined or null? (null is a value that means "nothing here, on purpose".) If so, line 3 returns Guest and the function stops. Line 5 reads the name only when a user is really there. The last three lines print Guest, Guest, and Asha, in that order.

There is a shorter way to write the same check, with two operators:

• user?.name reads name only if user is not null or undefined. Otherwise it stops and gives undefined, without throwing.
• a ?? b gives b when a is null or undefined. Otherwise it gives a.

1const user = undefined;2console.log(user?.name ?? "Guest");

Line 1 has no user. On line 2, user?.name stops and gives undefined. Then ?? gives "Guest" instead, so it prints Guest. Don't use this to hide data that must be there, such as the total of an order. Find out why that value is missing instead.

The step-through below follows the same kind of bug through two functions. The top frame is where the error happens. Then move down the stack trace to find where undefined came from.

1function showProfileName(user) {2  return user.name;3}4 5function renderProfile(user) {6  return showProfileName(user);7}8 9renderProfile(undefined);Run

Where you’ll use this

You will read errors every day. A page does not load. A button does nothing. A test fails. Each time, these steps are usually the fastest way to the problem:

1. Open the console. Find the first error that appeared after you clicked or loaded the page.
2. Read the name and the message before you change any code.
3. In the stack trace, find the first frame in your own file. Skip frames from browser add-ons or from code libraries you didn't write.
4. Look at the values on that line. Is a name spelled wrong? Is a property missing? Is a number too big or too small?
5. Still stuck? Search for the shared part of the message, and make a small copy of the problem.

The table below has one row per error name. Read each row as: "when I see this error, I ask this first, and the fix is often this."

Common misconceptions

Some questions ask about ideas. Others show a small program and ask what it prints. Each answer explains why it is right or wrong.

Key takeaways

• Read the error name first, then the message, then the stack trace.
• SyntaxError: JavaScript can't read the grammar. ReferenceError: no variable has that name. TypeError: the value exists, but can't do what the code asks.
• RangeError: a number is too big or too small for the job. URIError: the % codes in a web address are broken. EvalError: an old error that JavaScript no longer throws on its own.
• A stack trace lists calls newest first. Find the first frame in your own code, and check the values on that line.
• Search the words everyone sees, in quotes. Then read MDN, or the docs for the function in the top frame.

Coming next: Debugging in the browser.

1console.log(total);2const user = undefined;3user.name;