Reading TypeScript Errors

What a type error tells you

A signup form asks for an email and an age. The age arrives from a text box, so it's still text. TypeScript marks it, on purpose here:

1type SignupForm = { email: string; age: number };2 3const form: SignupForm = {4  email: "asha@example.com",5  age: "30",6};7console.log(form.age);

Line 1 says a SignupForm has an email that is a string (text) and an age that is a number. Lines 3 to 6 make a form with that type. Line 5 gives the age the text "30", and that's the line TypeScript marks. Line 7 still prints 30 when the code runs, because a type error doesn't stop the code.

Look at the list under the code. The error has three parts:

• Where: Line 5. In the code, a red wavy line, the squiggle, sits under age.
• What: Type 'string' is not assignable to type 'number'. "Assignable" means "allowed to be stored there". So it says: you gave a string, and this place needs a number.
• Which number: ts(2322). Every kind of TypeScript error has a number.

Many errors are longer. Under the first line they add more lines, each pushed a little to the right. Each of those lines says why the line above it is true. This lesson shows you how to read them, which errors you'll see most, and what to do when the red line isn't where the mistake is.

Where, what, and which number

Change the age yourself and watch the message. Type a new value for line 5. The list under the code updates as you type:

1type SignupForm = { email: string; age: number };2 3const form: SignupForm = {4  email: "asha@example.com",5  age: "30",6};7console.log(form.age);

With 30 or Number("30"), the value is a number, so the error is gone. With true the message says Type 'boolean' is not assignable to type 'number', and with null it says Type 'null' …. The first type changes with what you type. The second stays number, because the place still needs one. The number stays 2322, because it's still the same kind of mistake. An empty box gets a different number, 1109, and Expression expected: the line isn't finished, so there's nothing to check yet.

Here's how to read each part of an error:

The order matters. "Assignable" goes one way: a value of the first type must fit where the second type is needed. A number fits where number | null is needed, but number | null doesn't fit where only a number goes. (Structural typing explains how TypeScript decides what fits.)

A terminal shows the same error with a little more. How TypeScript works showed how to read the first lines. Here is the signup form saved as signup.ts and checked with npx tsc --noEmit:

signup.ts:5:3 - error TS2322: Type 'string' is not assignable to type 'number'.

5   age: "30",
    ~~~

  signup.ts:1:36
    1 type SignupForm = { email: string; age: number };
                                         ~~~
    The expected type comes from property 'age' which is declared here on type 'SignupForm'

Line 1 has the place, signup.ts:5:3 (file, line 5, column 3), then TS2322 and the message. Lines 3 and 4 show line 5 of the file with ~~~ under age. Lines 6 to 9 are a related note: it points at line 1 of the file and says The expected type comes from property 'age' which is declared here on type 'SignupForm'. That tells you where the number came from. If the type is the thing that's wrong, that's the line to change. Editors like VS Code list the same note under the error in their list of problems.

Long errors: read from the bottom up

A cart comes from a server. Its prices arrive as text, and showTotal wants a Cart with number prices. The error is six lines long, on purpose:

1type Item = { name: string; price: number };2type Cart = { items: Item[]; total: number };3type ApiCart = { items: { name: string; price: string }[]; total: number };4 5function showTotal(cart: Cart) {6  console.log(`Total: $${cart.total}`);7}8 9const fromServer: ApiCart = { items: [{ name: "Tea", price: "3" }], total: 3 };10showTotal(fromServer);

Line 1 says an Item has a number price. Line 2 says a Cart has a list of items and a total. Line 3 describes what the server sends, an ApiCart, where each price is a string. Lines 5 to 7 are showTotal, which takes a Cart. Line 9 makes the server's cart. Line 10 passes it to showTotal, and TypeScript marks the argument fromServer. It prints Total: $3 when it runs.

Here is the whole message, as the list under the code shows it:

Argument of type 'ApiCart' is not assignable to parameter of type 'Cart'.
  Types of property 'items' are incompatible.
    Type '{ name: string; price: string; }[]' is not assignable to type 'Item[]'.
      Type '{ name: string; price: string; }' is not assignable to type 'Item'.
        Types of property 'price' are incompatible.
          Type 'string' is not assignable to type 'number'.

The first line is the summary: the ApiCart doesn't fit where a Cart is needed. Each line under it is pushed further right, and answers "why?" about the line above. The TypeScript handbook calls these lines elaborations. Read them from the bottom up:

1. Line 6, the last: Type 'string' is not assignable to type 'number'. This is the real mismatch: text where a number goes.
2. Line 5: Types of property 'price' are incompatible. The text is a price.
3. Lines 4 and 3: the price belongs to one item, and that item is in an array of items.
4. Line 2: Types of property 'items' are incompatible. The array is the cart's items.

So the path is items, then one item, then price, and the problem is that it's text. Two fixes make sense: change ApiCart if the server really sends numbers, or turn each price into a number before calling showTotal.

Sometimes TypeScript shortens the path into one line. Break a server reply in different places and watch the middle line:

1type Price = { amount: number; currency: string };2type Product = { name: string; price: Price };3type CartLine = { product: Product; quantity: number };4 5const reply = {6  product: { name: "Tea", price: { amount: "3", currency: "USD" } },7  quantity: 2,8};9const line: CartLine = reply;

With Amount as text, the middle line is The types of 'product.price.amount' are incompatible between these types: the whole path, written like the code you'd use to reach the value. Currency missing stops the path at product.price, and its last line is a different error, Property 'currency' is missing …. Whatever the chain says above, the last line tells you what to fix.

In the playground, the error lands on line 9, under the variable line, because reply was made first and stored later. Write the same object straight into the typed variable, and TypeScript can point at the exact property:

1type Price = { amount: number; currency: string };2type Product = { name: string; price: Price };3type CartLine = { product: Product; quantity: number };4 5const line: CartLine = {6  product: { name: "Tea", price: { amount: "3", currency: "USD" } },7  quantity: 2,8};

Line 5 says the object is a CartLine from the start. The squiggle is now under amount on line 6, and the message is one line: Type 'string' is not assignable to type 'number'. When TypeScript can mark the exact spot, it doesn't need a chain.

One error with two chains

Some functions can be called in more than one way. Each way is called an overload (Function overloads explains them). When no way fits, you get error 2769, with one chain per overload. Here a click listener expects a key, on purpose:

1document.addEventListener("click", (event: KeyboardEvent) => {2  console.log(event.key);3});

Line 1 listens for "click" and says the event is a KeyboardEvent. Line 2 reads its key. The error is long. Point at the red line to read it. It has this shape:

• No overload matches this call. The summary.
• Overload 1 of 2, '(type: "click", …)', gave the following error. Then its chain, ending with Type 'PointerEvent' is missing the following properties from type 'KeyboardEvent': …
• Overload 2 of 2, '(type: string, …)', gave the following error. Then a second chain about a plain Event.

Read the chain for the overload you meant. You wrote "click", so overload 1 is yours, and its last line says a click gives a PointerEvent, which has no key. Overload 2 is the general one for any event name; it's rarely the one you meant. If you wanted keys, listen for "keydown":

1document.addEventListener("keydown", (event: KeyboardEvent) => {2  console.log(event.key);3});

Line 1 now listens for "keydown", which gives a KeyboardEvent, so there are no errors. (Typing events shows which event each name gives.)

The errors you'll meet most

A few error numbers make up most of what you'll see. In the table, X, Y, T, and p stand for the types and names from your code:

Pick a number to see a small example, then switch to the fixed version:

1let total: number = 0;2total = "7";3console.log(total);

A few things the examples show:

• 2322 and 2345 are the same check in two places: storing a value, and passing it to a function. The second one says Argument and parameter.
• 2741 and 2353 are opposites: a property the type needs is missing, or an extra one isn't in the type. 2353 only applies to an object written in place (Excess property checks explains why).
• 18048 says 'cake' is possibly 'undefined'. With a value that may be null, it's 18047. When the value has no simple name, like document.querySelector("input").value, the message says Object is possibly 'null' instead (2531, or 2532 for undefined). null and undefined covers the fixes.
• 7006 only appears when noImplicitAny is on, and strict turns it on. You get one error per parameter.

Where the red line lands

TypeScript marks the place where it finds that something doesn't fit. That's often not where you made the mistake. Here a function turns a name and an address into a user, with a typo:

1type User = { name: string; email: string };2 3function toUser(name: string, address: string) {4  return { name, emial: address };5}6 7const asha: User = toUser("Asha", "asha@example.com");8console.log(asha.email);

At step 1, line 4 spells emial, but line 4 is fine as far as TypeScript knows: toUser has no return type, so any object can come back. The first place the result must be a User is line 7, so that's where the error is. It even says Property 'email' is missing, which is true but sends you looking in the wrong place.

At step 2, line 3 says : User, the type the function should return. Now TypeScript checks the object on line 4 against User, and the error moves there. It says Did you mean to write 'email'?. Writing the type you meant moves the error to the line that breaks it. (Annotations and inference covers return types.)

When the same error shows up in several places, look for what they share:

1type CartItem = { name: string; price: number };2 3function makeItem(name: string, price: string) {4  return { name, price };5}6 7const cart: CartItem[] = [makeItem("Tea", "3"), makeItem("Cake", "4")];8console.log(cart.length);

Line 3 says makeItem takes a price that is a string. Line 4 returns it. Line 7 calls makeItem twice, and both calls get the same error, ending in Type 'string' is not assignable to type 'number'. You could fix both calls, but the mistake is the one parameter type on line 3. Change it to price: number and pass 3 and 4, and both errors go. Line 8 prints 2 either way.

Investigate with your editor

Your editor knows every type in your code. When an error confuses you, ask it. Point at a name to see its type. In this lesson, a // ^? line asks the same question and writes the answer after it. Here is a long line with two errors in it:

1const prices = new Map([["tea", 3], ["cake", 4]]);2const cart = ["tea", "cake"];3const total = cart.map((id) => prices.get(id)).reduce((sum, price) => sum + price, 0);4console.log(total);

Line 1 makes a Map from product ids to prices. Line 2 is the cart, a list of ids. Line 3 turns each id into its price with map, then adds them up with reduce (map, filter, and reduce explains both). TypeScript marks sum and price on line 3: 'sum' is possibly 'undefined', and the same for price. But where does the undefined come from? Split the line into steps, and ask about the first one:

1const prices = new Map([["tea", 3], ["cake", 4]]);2const cart = ["tea", "cake"];3const linePrices = cart.map((id) => prices.get(id));4//    ^?5const total = linePrices.reduce((sum, price) => sum + price, 0);6console.log(total);

Line 3 is the first step, with its own name, linePrices. The query on line 4 answers const linePrices: (number | undefined)[]: an array where each item is a number or undefined. So the undefined comes from prices.get(id). A Map gives back undefined for an id it doesn't have. The errors are now on line 5, where the sum uses those values. Give a missing price a value with ?? 0:

1const prices = new Map([["tea", 3], ["cake", 4]]);2const cart = ["tea", "cake"];3const linePrices = cart.map((id) => prices.get(id) ?? 0);4//    ^?5const total = linePrices.reduce((sum, price) => sum + price, 0);6//    ^?7console.log(total);

Line 3 adds ?? 0, which gives 0 when the left side is undefined (Nullish coalescing and optional chaining). The query on line 4 now answers const linePrices: number[], and the one on line 6 answers const total: number. No errors, and line 7 prints 7.

A starting value can cause errors too. An empty object {} has the type {}: an object with no properties.

1type CartItem = { name: string; price: number };2const cart: CartItem[] = [{ name: "Tea", price: 3 }, { name: "Cake", price: 4 }];3const byName = cart.reduce((totals, item) => {4  totals[item.name] = item.price;5  return totals;6}, {});7console.log(byName);

Line 3 builds an object with reduce, starting from {} on line 6. Line 4 stores each price under its item's name, and TypeScript marks it: Element implicitly has an 'any' type because expression of type 'string' can't be used to index type '{}'. Read the end first: the type is {}, which has no room for names. The fix is to name the type you mean and give it to the starting value:

1type CartItem = { name: string; price: number };2const cart: CartItem[] = [{ name: "Tea", price: 3 }, { name: "Cake", price: 4 }];3type PriceList = Record<string, number>;4const start: PriceList = {};5const byName = cart.reduce((totals, item) => {6  totals[item.name] = item.price;7  return totals;8}, start);9console.log(byName);

Line 3 names the type PriceList: an object whose keys are strings and whose values are numbers (Utility types covers Record). Line 4 makes the empty start with that type, and line 8 passes it in. reduce now knows what it's building, so there are no errors, and line 9 prints { Tea: 3, Cake: 4 }. Point at byName to see const byName: PriceList.

These moves work on most confusing errors:

A theme from the address bar

A settings page reads the theme from the page's address, like ?theme=dark, with URLSearchParams. Fix it the way you would in a real project: read the last line, fix that, and read again.

1type Theme = "light" | "dark";2 3function setTheme(theme: Theme) {4  console.log(`Theme: ${theme}`);5}6 7const params = new URLSearchParams("?theme=dark");8setTheme(params.get("theme"));

Line 1 says a Theme is "light" or "dark", and lines 3 to 5 set it. Line 7 reads the address. At step 1, line 8 passes params.get("theme") straight in. Its type is string | null, and the error's last line names only null. At step 2, the if on line 9 removes null, and a second error appears on line 10 about string. It was there all along. TypeScript stops at the first reason it finds, so fixing one reason can show the next. Step 3 checks for the two allowed values (Narrowing explains how the if changes the type), and the errors are gone.

Now practise reading the number. Sort each line by the error TypeScript gives it:

Common mix-ups

• "The first line of an error is the important one." No. It's a summary. The last line of the chain usually names the real mismatch.
• "The red line is where the mistake is." No. It's where TypeScript noticed. Writing the type you meant, like a return type, moves the error closer to the cause.
• "In 'X is not assignable to Y', X is what the place needs." No. X is what you gave. Y is what the place needs.
• "Fixing what the last line says fixes the error." Not always. It names the first reason TypeScript found. Another reason, like the string in the theme, can appear once it's fixed.
• "An error means the code won't run." No. The code still runs with the types removed. The signup form prints 30, and the cart prints Total: $3.
• "Adding any fixes an error." It hides it. The value is just as wrong when the code runs.

Practice exercises

Each exercise is TypeScript. Press Edit & run on the starter code to try a fix: the errors update as you type, and you can point at a name to see its type. Guess first, then use the hints.

function addToCart(name: string, quantity: number) {
  console.log(`${quantity} x ${name}`);
}

addToCart("Tea", "2");

1function addToCart(name: string, quantity: number) {2  console.log(`${quantity} x ${name}`);3}4 5addToCart("Tea", 2);

1type Address = { street: string; zip: string };2type Customer = { name: string; address: Address };3type ApiCustomer = { name: string; address: { street: string; zip: number } };4 5function shipTo(customer: Customer) {6  console.log(`${customer.name}, ${customer.address.zip}`);7}8 9const fromServer: ApiCustomer = { name: "Asha", address: { street: "Oak Street 12", zip: 56001 } };10shipTo(fromServer);

1type Address = { street: string; zip: string };2type Customer = { name: string; address: Address };3 4function shipTo(customer: Customer) {5  console.log(`${customer.name}, ${customer.address.zip}`);6}7 8const fromServer: Customer = { name: "Asha", address: { street: "Oak Street 12", zip: "56001" } };9shipTo(fromServer);

1type Profile = { name: string; email: string; newsletter: boolean };2 3const asha: Profile = {4  name: "Asha",5  email: "asha@example.com",6};7console.log(asha.newsletter ? "Subscribed" : "Not subscribed");

1type Profile = { name: string; email: string; newsletter: boolean };2 3const asha: Profile = {4  name: "Asha",5  email: "asha@example.com",6  newsletter: true,7};8console.log(asha.newsletter ? "Subscribed" : "Not subscribed");

1type Product = { name: string; price: number };2 3function toProduct(name: string, cents: number) {4  return { name, prise: cents / 100 };5}6 7const tea: Product = toProduct("Tea", 300);8console.log(tea.price);

1type Product = { name: string; price: number };2 3function toProduct(name: string, cents: number): Product {4  return { name, price: cents / 100 };5}6 7const tea: Product = toProduct("Tea", 300);8console.log(tea.price);

1const stock = new Map([["tea", 5], ["cake", 2]]);2const order = ["tea", "cake", "scone"];3const left = order.map((id) => stock.get(id)).reduce((sum, count) => sum + count, 0);4console.log(left);

1const stock = new Map([["tea", 5], ["cake", 2]]);2const order = ["tea", "cake", "scone"];3const counts = order.map((id) => stock.get(id) ?? 0);4//    ^?5const left = counts.reduce((sum, count) => sum + count, 0);6console.log(left);

1const search = document.createElement("input");2search.addEventListener("click", (event: KeyboardEvent) => {3  if (event.key === "Enter") console.log("Search");4});

1const search = document.createElement("input");2search.addEventListener("keydown", (event: KeyboardEvent) => {3  if (event.key === "Enter") console.log("Search");4});

Check your understanding

The quiz shows its code without the checker, so the error list doesn't give the answers away. Read each error the way the lesson does: what you gave, what the place needs, and the last line of the chain.

Key takeaways

• An error has a place, a message, and a number like ts(2322). Search for the number as TS2322.
• In Type 'X' is not assignable to type 'Y', X is what you gave and Y is what the place needs.
• A long error is a chain: each line says why about the one above. Start at the last line, and use the lines above as the path.
• For "No overload matches this call", read the chain for the way of calling you meant.
• The red line is where TypeScript noticed. Write the type you meant, like a return type, to move it to the mistake.
• Point at names, add ^? queries, split long lines, and name types to see where a type went wrong.
• Fixing the last line can reveal the next reason. Read again after each fix.

Coming next: Habits of good TypeScript. It collects the habits that keep errors like these rare and easy to read: letting inference work, avoiding any, and modelling states with unions.