Reading and debugging type errors
How to read a long TypeScript error from the bottom up, inspect what the checker inferred, and corner a confusing error until it points at the real line.
The editor and the TypeScript language serverType annotations and type inferenceStructural typing and excess property checks
Reading and debugging type errors
The player loads from youtube-nocookie.com when you press play. Nothing reaches YouTube before that.
Not started
What you'll learn
- A long assignability error is a chain: the first line names where the checker gave up, and each indented line drills one level deeper, so the last line usually names the actual mismatch.
- Every error has a code such as `TS2345` or `TS2741`; the code identifies the kind of problem and is a far better search term than the message, which embeds your own type names.
- Hovering, or a `// ^?` comment in the TypeScript Playground, shows what the checker actually inferred, which is often not what you assumed.
- Annotating an intermediate variable moves the error to where the wrong value was created, instead of where it was finally used.
- Hovers show intersections and aliases unexpanded; a `Prettify<T>` helper flattens them into one object type you can read.
- When you must silence an error, prefer `@ts-expect-error` to `@ts-ignore`, because it reports itself as unused once the error is gone.
The error is a trail, not a verdict
Sooner or later you’ll get an error like this:
type Address = { street: string; city: string; postcode: string };
type Customer = { name: string; address: Address };
type Order = { id: string; customer: Customer; total: number };
declare function saveOrders(orders: Order[]): void;
const rows = [
{ id: "o_2", customer: { name: "Bo", address: { street: "1 Elm St", city: "York" } }, total: 12 },
];
saveOrders(rows);
error TS2345: Argument of type '{ id: string; customer: { name: string; address: { street: string; city: string; }; }; total: number; }[]' is not assignable to parameter of type 'Order[]'.
Type '{ id: string; customer: { name: string; address: { street: string; city: string; }; }; total: number; }' is not assignable to type 'Order'.
The types of 'customer.address' are incompatible between these types.
Property 'postcode' is missing in type '{ street: string; city: string; }' but required in type 'Address'.
It looks like a wall. It’s actually a stack trace for a comparison. The checker asked “is this array assignable to Order[]?”, and to answer, it compared the elements, then customer, then address, then each property. The first line is where it started; each indented line is one step deeper. The bottom line is where it found the actual problem: no postcode.
So read these bottom-up. Start at the last line, understand the mismatch, then read upward only as far as you need to find where in your data it is.
Error codes are search terms
Every diagnostic has a number. A few you’ll meet constantly:
TS2322: a value isn’t assignable to the declared type.TS2345: an argument isn’t assignable to the parameter.TS2339: a property doesn’t exist on a type.TS2741: a required property is missing.TS7006: a parameter implicitly has typeany.
The message embeds your type names, so pasting it into a search engine finds nothing. The code names the category of problem, and searching for TS2741 finds people who hit the same kind of error with entirely different types.
Look at what the checker sees
Most confusing errors come from a type that isn’t what you think it is. Don’t guess; ask. In the editor, hover over a variable to see its inferred type, as covered in the editor and the language server. In the TypeScript Playground, a comment with ^? under an identifier prints its type inline and keeps it visible while you edit:
const statuses = ["open", "closed"];
// ^? const statuses: string[]
That’s the moment you learn the array was widened to string[], not the "open" | "closed" you wanted, and that the error further down is about widening, not about the function you were staring at.
Move the error to the bug
TypeScript reports a mismatch where two types meet, which isn’t always where the mistake was made. In the example above, the error sits on saveOrders(rows), though the bug is inside the literal. Annotate the intermediate value with what you meant:
const rows: Order[] = [
{ id: "o_2", customer: { name: "Bo", address: { street: "1 Elm St", city: "York" } }, total: 12 },
];
// error TS2741: Property 'postcode' is missing in type
// '{ street: string; city: string; }' but required in type 'Address'.
Now the comparison happens at creation, and the error underlines the address object itself. This works anywhere: a function’s return value, a callback’s result, a step in a long chain. Pinning the expected type at each step is like a plumber closing valves one at a time to find which section of pipe leaks. Once the error moves to the right line, you can delete the annotations you don’t need.
When an error mentions a type truncated with ..., the noErrorTruncation compiler option prints it in full.
Flatten types you can’t read
Hovers show a type the way it was written. An intersection or a stack of utility types shows up as names, not properties:
type Timestamps = { createdAt: Date; updatedAt: Date };
type Row = Customer & Timestamps;
// hover: type Row = Customer & Timestamps
type Prettify<T> = { [K in keyof T]: T[K] } & {};
type PrettyRow = Prettify<Customer & Timestamps>;
// hover: { name: string; address: Address; createdAt: Date; updatedAt: Date }
Prettify is a mapped type that copies every property into a fresh object type, which makes the editor compute and display the result. The trailing & {} is a common trick that nudges the hover to show the expanded form. It doesn’t change what’s assignable, only what you see.
When you need to silence one
Sometimes the types are wrong and you can’t fix them yet, perhaps in a library’s declarations. Two comments suppress the error on the next line:
// @ts-ignore
legacyLib.init(42);
// @ts-expect-error: legacyLib's types say init takes a string; it accepts numbers.
legacyLib.init(42);
@ts-ignore stays silent forever, even after the library fixes its types, and even if a different error later appears on that line. @ts-expect-error fails with TS2578: Unused '@ts-expect-error' directive when there’s no longer an error to suppress, so it cleans up after itself. Always prefer it, and add a reason after the colon. That same failure-when-unused behavior is what makes it a tool for testing your types.
About the video
Joy of Code’s five-minute episode, part of a TypeScript fundamentals series, shows how to read an error’s message chain, introduces Matt Pocock’s TypeScript Error Translator for turning messages into plain English, and gives a general troubleshooting approach. It’s short and from 2022, so the inspection and isolation techniques above go further than it does. The Josh tried coding video in the links shows the Pretty TypeScript Errors extension, which formats long errors like the one at the top of this page into something far easier to scan.
Check yourself
A four-line error starts with `Argument of type '{...}[]' is not assignable to parameter of type 'Order[]'`. Which line should you read first, and why?
The last one. The first line only says where the checker gave up, at the outermost comparison. Each indented line goes one level deeper into the types, and the bottom line names the specific property or value that didn't match.
Why is searching for `TS2741` more useful than pasting the error message into a search engine?
The message includes your own type and property names, so it rarely matches anyone else's. The code names the category, here a required property missing from an object, and finds explanations of that category regardless of the types involved.
An error appears on `saveOrders(rows)`, but the bug is in how `rows` was built twenty lines earlier. How do you make the error point at the bug?
Annotate `rows` with the type you intended, such as `const rows: Order[] = [...]`. The checker then compares the value with `Order[]` where it is created, and the error lands on the exact property that is wrong.
Why does hovering over `type Row = Customer & Timestamps` not show you the full list of properties, and what helps?
The editor shows the type as written, an intersection of two names, rather than computing the merged object. A helper such as `type Prettify<T> = { [K in keyof T]: T[K] } & {}` maps over every key and forces the hover to display one flat object type.
What does `@ts-expect-error` do that `@ts-ignore` doesn't?
Both suppress an error on the next line. `@ts-expect-error` also fails with `Unused '@ts-expect-error' directive` when there's no error to suppress, so once someone fixes the underlying problem, the stale comment gets noticed and removed instead of hiding the next real error on that line.
Go deeper
Notes
Notes are saved to your account.
Everything else on this page works without one — progress and bookmarks keep themselves in this browser and come with you when you sign in. Notes are the one thing worth not trusting to a browser you might clear.
Your notes could not be loaded.