Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

TypeScript says the caught error is of type unknown

Error'err' is of type 'unknown'.

Short answer

TypeScript types catch variables as unknown when strict mode (useUnknownInCatchVariables) is on, because anything can be thrown in JavaScript. You cannot read err.message on unknown. Narrow first with instanceof Error, typeof, or a type guard function. The same rule applies to any value typed unknown, such as a function result.

  • Applies to TypeScript 5, React 19
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check whether strict mode is on. In TypeScript 4.4 and later, the strict family of options turns on useUnknownInCatchVariables, which makes catch variables unknown.

    npx tsc --showConfig | grep -E "strict|useUnknownInCatchVariables"
  2. 2Match what you see, then jump to its fix

    1. 1Property 'message' does not exist on type 'unknown'.The catch variable is unknown under strict modeFix
    2. 2'obj' is of type 'unknown'. (code 18046) on a property accessA function returns unknown and the result is used directlyFix
    3. 3Many existing catch blocks fail to compile after turning strict onYou want a different default for catch variablesFix

What does the error look like?

  • 'err' is of type 'unknown'.
  • Property 'message' does not exist on type 'unknown'.
  • TS18046

Cause 1 of 3

The catch variable is unknown under strict mode

1Check

Look at the catch clause. With the flag on, err is unknown, so reading err.message is an error until you prove it is an Error.

try {
  await saveOrder();
} catch (err) {
  console.error(err.message); // error
}

2Fix

Narrow with instanceof Error before using the properties.

try {
  await saveOrder();
} catch (err) {
  if (err instanceof Error) {
    console.error(err.message);
  }
}

3Verify

Run the compiler. The error on that line is gone.

npx tsc --noEmit

Confirmed by typescriptlang.org

Did this fix it?

Cause 2 of 3

A function returns unknown and the result is used directly

1Check

A value typed unknown allows no operation until narrowed. This includes your own helper that returns unknown for safety, like a parser.

function safeParse(s: string): unknown {
  return JSON.parse(s);
}
const data = safeParse(text);
data.name; // error

2Fix

Narrow with typeof and in, or write a type predicate that states the shape.

type User = { name: string };
function isUser(v: unknown): v is User {
  return typeof v === 'object' && v !== null && 'name' in v && typeof v.name === 'string';
}
const data = safeParse(text);
if (isUser(data)) {
  console.log(data.name);
}

3Verify

Run the compiler. The property access inside the guarded block compiles.

npx tsc --noEmit

Confirmed by typescriptlang.org

Did this fix it?

Cause 3 of 3

You want a different default for catch variables

1Check

The flag can be set on its own. TypeScript 4.0 also allowed an explicit annotation on one catch clause.

grep -n "useUnknownInCatchVariables" tsconfig.json

2Fix

Prefer narrowing. If you must, annotate a single clause as unknown to be explicit, or turn the flag off in tsconfig.json and accept that err becomes any.

{
  "compilerOptions": {
    "strict": true,
    "useUnknownInCatchVariables": false
  }
}

3Verify

Run the compiler again.

npx tsc --noEmit

Confirmed by typescriptlang.org

Did this fix it?

How do I stop it coming back?

  • Write one small helper that turns an unknown caught value into a message string, and reuse it.
  • Keep useUnknownInCatchVariables on: it forces checks that stop crashes when something other than an Error is thrown.
  • Return unknown, not any, from parsing helpers and validate the shape at the boundary.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Web apps

TypeScript rejects MUI Data Grid columns that set a type

A TypeScript error inside a column's renderCell callback

A columns array declared without a type is inferred with type as a plain string, which the Data Grid's column type union does not accept.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.