Common Errors, Strictness Migration and Reading Error Messages

This is the last lesson of the series. The first lessons showed single errors as they came up; here we collect them, show how to read the long ones, and then do a real migration: a small loose project, step by step, with an error count after every step. We finish with @ts-expect-error, any against unknown, and putting the check in CI and in a linter. For interview-style questions on the same topics see Full-Stack Q&A, Lesson 3 and Frontend Depth, Lesson 4. The settings used are from Lesson 0 and Lesson 5.

Words used in this lesson

• Diagnostic is the compiler's word for an error, warning or suggestion. An error has a code such as TS2322.
• Strict flag is one of the checks inside strict (noImplicitAny, strictNullChecks and so on).
• Migration here means moving a project from loose or plain JavaScript to strict TypeScript.
• allowJs lets tsc read .js files. checkJs makes it also type check them.
• Type assertion is x as T: you tell the checker to trust you.
• Suppression comment is // @ts-ignore or // @ts-expect-error: it hides an error on the next line.
• Linter is a tool (ESLint) that reads code for bad patterns. It is not a type checker, but with type information it can see more.
• CI (continuous integration) is a server that runs your checks on every change.
• Exit code is the number a program returns: 0 means success.

Reading a long error: bottom up

A short error is easy. A long one looks scary because tsc prints a chain: a top line that says what failed, then indented lines that say why, each one going deeper. The top line is the symptom. The last indented line is usually the cause. Here is a nested object passed to a function:

type Order = { id: number; customer: { name: string; address: { city: string; zip: string } }; items: { sku: string; qty: number }[] };function ship(o: Order) { return o.id; }const input = {  id: 1,  customer: { name: "Ada", address: { city: "London", zip: 12345 } },  items: [{ sku: "a", qty: 1 }, { sku: "b", qty: "2" }],};ship(input);

src/e.ts(9,6): error TS2345: Argument of type '{ id: number; customer: { name: string; address: { city: string; zip: number; }; }; items: ({ sku: string; qty: number; } | { sku: string; qty: string; })[]; }' is not assignable to parameter of type 'Order'.  The types of 'customer.address.zip' are incompatible between these types.    Type 'number' is not assignable to type 'string'.

Read it from the bottom: "number is not assignable to string", on the property customer.address.zip. That is the fix: the zip is a number in my data and a string in the type. The long first line is only a dump of the whole argument; you do not need to read it.

Two lessons from this one. First, tsc told me about zip but not about qty: "2", which is also wrong. It reports the first difference it finds in the chain. After I fix zip, the next run shows the qty problem. Fix one, run again. Second, an error can sit far from the place you wrote the wrong thing: the mistake was in input, and the error is on the call ship(input).

A deeper chain, a Promise with a wrong item inside:

function load(): Promise<{ id: number; tags: string[] }> {  return Promise.resolve({ id: 1, tags: [1, 2] });}

src/e.ts(11,3): error TS2322: Type 'Promise<{ id: number; tags: number[]; }>' is not assignable to type 'Promise<{ id: number; tags: string[]; }>'.  Type '{ id: number; tags: number[]; }' is not assignable to type '{ id: number; tags: string[]; }'.    Types of property 'tags' are incompatible.      Type 'number[]' is not assignable to type 'string[]'.        Type 'number' is not assignable to type 'string'.

Five levels deep. The last line is the answer: a number where a string is needed, and the line above it says it is inside tags. A third pattern is a callback with the wrong parameter, where the cause is a missing property:

error TS2322: Type '(req: { path: string; }) => Promise<string>' is not assignable to type '(req: { url: string; }) => Promise<string>'.  Types of parameters 'req' and 'req' are incompatible.    Property 'path' is missing in type '{ url: string; }' but required in type '{ path: string; }'.

The bottom line says: the caller will give an object with url, but my function wants path.

The errors you will see most

I put all of these in one file with the Lesson 0 config (strict, noUncheckedIndexedAccess) and ran tsc. Here are the real messages, with what they mean and the usual fix.

(The table has 16 rows, more than ten; the first twelve are the ones I meet daily.) Four notes:

• TS2552 versus TS2304. For an undeclared name close to a real one, tsc says TS2552: Cannot find name 'undefinedVar'. Did you mean 'undefined'?. Without a near match, it says TS2304: Cannot find name 'foo'. Same problem, different code.
• TS18048 versus TS2532. Both mean "may be undefined". In my file, v.length on a variable v gave TS18048: 'v' is possibly 'undefined', and a.b.c gave TS18048: 'a.b' is possibly 'undefined', but arr[0].toFixed() gave the older TS2532: Object is possibly 'undefined', because arr[0] is an expression and not a name.
• TS2564 and erasableSyntaxOnly. The shortcut constructor(public name: string) fixes TS2564, but it is rejected by erasableSyntaxOnly (TS1294, Lesson 0). Declare the field and set it in the constructor.
• Fixes that I compiled. I checked that Record<string, string> for the object, a k is keyof typeof o guard, v?.length ?? 0, a field with a default, and an optional field all compile without errors.

any against unknown

When you do not know a type, you have two choices, and they are opposites.

function useAny(x: any) { return x.foo.bar(); }function useUnknown(x: unknown) { return x.foo; }const j = JSON.parse("{}");const k: unknown = JSON.parse("{}");const s1: string = j;const s2: string = k;

src/e.ts(11,42): error TS18046: 'x' is of type 'unknown'.src/e.ts(15,7): error TS2322: Type 'unknown' is not assignable to type 'string'.

useAny and s1 compiled with no error: any turns the checker off for that value, and it spreads (j is any, so everything made from it is any). unknown means "something, I do not know what": you may hold it and pass it, but you must narrow it before you use it (typeof, in, instanceof, or a Zod schema, Lesson 6). Use unknown for outside data and for catch (e). Use any almost never.

@ts-expect-error against @ts-ignore

Both comments hide the error on the next line. They differ when there is no error:

// @ts-ignoreconst a: number = "x";// @ts-expect-errorconst b: number = "x";// @ts-expect-errorconst c: number = 5;// @ts-ignoreconst d: number = 5;

src/e.ts(5,1): error TS2578: Unused '@ts-expect-error' directive.

That was the only message. Lines 1 to 4 were silent. @ts-ignore on line 7 (a correct line) also stayed silent forever. @ts-expect-error says "I expect an error here", and if the error goes away, TypeScript tells you to remove the comment. That makes it the safer one:

• Use @ts-expect-error in tests of types (a line that must fail) and for a known problem with a note: // @ts-expect-error library types are wrong, see issue #123.
• Avoid @ts-ignore. It stays after the code is fixed and may later hide a different error on that line.
• Neither is a fix. Prefer a narrowing check, a better type, or unknown.

A last pitfall, strictFunctionTypes. A handler that accepts only a mouse event cannot be used where a mouse-or-keyboard handler is wanted:

error TS2322: Type '(e: MouseEvent) => void' is not assignable to type 'Handler'.  Types of parameters 'e' and 'e' are incompatible.    Type 'KeyboardEvent | MouseEvent' is not assignable to type 'MouseEvent'.      Type 'KeyboardEvent' is missing the following properties from type 'MouseEvent': button, buttons, clientX, clientY, and 14 more.

Read the bottom: the caller may pass a keyboard event, and your function would break on it.

Migrating a loose project to strict

Do not turn on strict in a big project and look at 4000 errors. Go in steps, keep the build green at each step, and commit after each. I made a small project to show the steps: four JavaScript files (utils, user, api, main) written the way loose code is written: no types, a class that sets this.name without declaring it, a catch (e) that reads e.message, a function that uses this, a wrong .bind call and an argv[0].length.

Step 1: let TypeScript read the JavaScript (allowJs)

{ "compilerOptions": { "target": "es2022", "module": "nodenext", "allowJs": true,  "checkJs": false, "noEmit": true, "types": ["node"], "strict": false },  "include": ["src"] }

tsc printed nothing, exit code 0. With allowJs the JS files are part of the project (imports between .ts and .js work) and nothing is checked yet. Set strict to false explicitly here: since TypeScript 6.0, strict is on by default (Lesson 0), so a "loose" project must say so.

Running the JavaScript showed a real bug that the types would have found:

TypeError: Cannot read properties of undefined (reading 'length')    at .../src/main.js:11:21

It is argv[0].length when no argument is given.

Step 2: check the JavaScript (checkJs)

Set "checkJs": true. Now tsc reads the JS and infers types.

src/user.js(6,36): error TS2339: Property 'balance' does not exist on type 'Account'.

One error, because with strict off most things quietly become any. You can also opt in one file at a time with // @ts-check on the first line and keep checkJs off; I checked a file with JSDoc types that way:

// @ts-check/** * @param {number} a * @param {string} [label] * @returns {string} */export function fmt(a, label = "n") { return label + a.toFixed(1); }fmt("1");

src/jsdoc.js(10,5): error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.

JSDoc comments are the way to type a JavaScript file that you cannot rename yet. These two steps give you value without touching the code.

Step 3: rename to .ts, still strict: false

I renamed the four files to .ts (and changed the imports to .ts, with allowImportingTsExtensions). Four errors, all TS2339: the class used this.name and this.balance without declaring them. In a .ts class, fields must be declared:

export class Account {  name: string;  balance = 0;  constructor(name) { this.name = name; }

After that: 0 errors with strict: false. The code is TypeScript now, and still loose.

Step 4: the strict flags, one at a time

Now turn on the flags of strict one by one, in this order. Counts are for my small project:

Why this order: noImplicitAny first, because until the any parameters are typed, the other checks have nothing to look at. In my first try I turned on every flag in a row without fixing, and strictNullChecks added no errors at all (the count stayed at 14): the ten untyped parameters were any, and any hides null mistakes. That is why you fix noImplicitAny before moving on.

The fixes were small:

// 4a  type the parameters (and give the shapes a name)export type Item = { price: number; qty: number };export type User = { id: number; name: string; email: string };export function sum(items: Item[]) { /* ... */ }export function findUser(users: User[], id: number) { return users.find((u) => u.id === id); }// 4b  the undefined case was realif (hit) console.log(makeLabel(hit));// 4d  the call had one argument too manyexport const add5 = add.bind(null, 5);// 4e  an arrow function keeps `this` from the objectinc() { return () => this.count + 1; }// 4f  narrow the unknownconsole.log("failed:", e instanceof Error ? e.message : e);// 5   the argv bug from step 1console.log(argv[0]?.length ?? 0);

I also tried the same in one go: with "strict": true and noUncheckedIndexedAccess together on the untouched .ts files, tsc reported 18 errors. Doing it in steps turned 18 errors into six small, ordered jobs. The final config, with 0 errors:

{ "compilerOptions": { "target": "es2022", "module": "nodenext", "strict": true,  "noUncheckedIndexedAccess": true, "noEmit": true, "skipLibCheck": true, "types": ["node"] },  "include": ["src"] }

In a big project the same order works with a twist: you cannot fix all the errors at once. Options I would use, in order of preference: (1) turn a flag on for the whole project and fix all errors, if there are fewer than a few dozen; (2) move files to .ts and strict one folder at a time, with a second tsconfig for the strict folder that includes only the folders already clean (a tsc run with both configs in CI); (3) as a last resort, // @ts-expect-error with a TODO on the lines you cannot fix today, so the count can only go down. Avoid mass as any.

Type checking in CI

tsc is the type checker, so it belongs in CI. I ran a file with one error three ways:

Any non-zero code fails a CI job. Note the first row: by default, tsc writes JavaScript even when there are errors, so a build script that ignores the exit code can ship broken code. For a project where a bundler writes the output, use tsc --noEmit as a check. A sketch (not run):

{ "scripts": { "typecheck": "tsc --noEmit", "lint": "eslint .", "test": "node --test" } }

# .github/workflows/ci.yml  (not run)on: [push, pull_request]jobs:  check:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v4      - uses: actions/setup-node@v4        with: { node-version: 22 }      - run: npm ci      - run: npm run typecheck      - run: npm run lint      - run: npm test

Add "incremental": true to speed up repeat runs, and for a monorepo use tsc -b (Lesson 5). Also run the type check in your editor, so you see the error before CI does.

Lint rules that help

A linter does not replace tsc. It catches things tsc is happy with. In a separate folder (TypeScript 6.0.3, see the note at the top) I set up ESLint with typescript-eslint and its strictTypeChecked preset, which uses type information, and ran it on this file:

async function save(x: number) { return x; }export function run(input: any, maybe?: { v: string }) {  save(1);  const n = input.count;  const s = maybe!.v;  // @ts-ignore  const bad: number = "x";  return [n, s, bad];}

tsc printed nothing and exited 0 on it, because @ts-ignore hid the real error and the rest is legal. ESLint reported 8 problems:

1:1   error  Async function 'save' has no 'await' expression         @typescript-eslint/require-await3:28  error  Unexpected any. Specify a different type                 @typescript-eslint/no-explicit-any4:3   error  Promises must be awaited, end with a call to .catch, ... @typescript-eslint/no-floating-promises5:9   error  Unsafe assignment of an `any` value                      @typescript-eslint/no-unsafe-assignment5:19  error  Unsafe member access .count on an `any` value            @typescript-eslint/no-unsafe-member-access6:13  error  Forbidden non-null assertion                             @typescript-eslint/no-non-null-assertion7:3   error  Use "@ts-expect-error" instead of "@ts-ignore", ...      @typescript-eslint/ban-ts-comment9:3   error  Unsafe return of a value of type `any[]`                 @typescript-eslint/no-unsafe-return

The rules worth knowing:

• no-floating-promises: a promise that is not awaited (save(1)). Its error is silent, because tsc does not mind.
• no-explicit-any and the no-unsafe-* family: stop any from spreading.
• ban-ts-comment: allows @ts-expect-error (with a description) and bans @ts-ignore.
• no-non-null-assertion: the ! operator. It is a cast that says "this is not null"; a runtime TypeError is the cost when you are wrong.
• consistent-type-imports: keeps import type consistent (Lesson 5). I did not run this one.

The config was a few lines: eslint.configs.recommended, tseslint.configs.strictTypeChecked, and parserOptions: { projectService: true } so ESLint can ask TypeScript for types. The type-aware rules are slower than plain ones.

Try it

1. Write a function with a nested object argument that has two wrong fields. Run tsc. How many errors are reported? Fix one and run again.
2. Make a file that triggers TS2322, TS2339, TS2345 and TS7006. Read each from the bottom line up.
3. Write // @ts-expect-error above a correct line. What does tsc say?
4. Take a small JS file, add // @ts-check and a JSDoc @param {number}. Call it with a string. What happens?
5. Turn strict off, then on again. Which of the four errors in exercise 2 disappear when it is off?
6. Make let n = JSON.parse("1") and let m: unknown = JSON.parse("1"). Which can you pass to a function that takes string?

Answers.

1. One error, for the first mismatch (customer.address.zip in my run). After fixing it, the next run showed the second one.
2. Each has the cause in the last line, such as Type 'string' is not assignable to type 'number'.
3. error TS2578: Unused '@ts-expect-error' directive.
4. error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'., with checkJs off.
5. TS7006 (needs noImplicitAny). TS2322, TS2339 and TS2345 stay. (In my Lesson 0 test, TS18048 also disappeared with strict off.)
6. The any one (n) compiles, and it is the dangerous one. m is refused with Type 'unknown' is not assignable to type 'string'.

Interview questions

Key takeaways

• Read errors from the bottom: the last indented line is the cause. tsc shows the first difference, so fix one and run again.
• A dozen codes cover most days: TS2322, TS2339, TS2345, TS7006, TS18048/TS2532, TS2564, TS2307, TS7053, TS2304, TS2741, TS2554.
• unknown forces a check, any spreads silently. Prefer @ts-expect-error to @ts-ignore, with a reason.
• Migrate in steps: allowJs, checkJs or // @ts-check, rename to .ts, then noImplicitAny first, strictNullChecks, the rest, and noUncheckedIndexedAccess last. Keep the build green and commit at each step.
• Run tsc --noEmit in CI; plain tsc can write JavaScript even when it fails.
• Add a type-aware linter for what tsc allows: floating promises, any, !, @ts-ignore.

What's next

That is the end of the series. You can run tsc and read its messages (Lesson 0), type values and functions (Lessons 1 to 3), build types (Lesson 4), set up real projects (Lesson 5) and validate outside data (Lesson 6). To practise, take a small JavaScript project of your own and migrate it with the steps above, then answer the questions in Full-Stack Q&A, Lesson 3 and Frontend Depth, Lesson 4 out loud.