Allow type annotation on catch clause variable

TypeScript Version: 2.6.1

const rejected = Promise.reject(new Error());

async function tryCatch() {
  try {
    await rejected;
  } catch (err: Error) { // TS1196: Catch clause variable cannot have a type annotation
    // Typo, but `err` is `any`, so it results in runtime error
    console.log(err.mesage.length);
  }
}

function promiseCatch() {
  rejected.catch((err: Error) => { // OK
    // Compiler error; Yay!
    console.log(err.mesage.length);
  });
}

This was discussed in #8677 and #10000. It was closed as "fixed" in #9999, but as far as I can tell neither of the issues was actually resolved. In either event, I'd like to make a case for allowing type annotations in catch clauses.

Especially with the introduction of downlevel async functions, I'd suggest that disallowing catch clause type annotations leads to less safe code. In the example, the two methods of handling the promise are functionally equivalent, but one allows you to type the error, and the other doesn't. Without writing extra code for the try/catch version (if (err instanceof Error) { or const e: Error = err or something), you'll get a runtime error that you wouldn't get with the pure Promise version.

The primary rationale for not allowing this is that any object can be thrown, so it's not guaranteed to be correct. However, most of the benefit of TypeScript comes from making assertions about your and other people's code that can't be strictly guaranteed (especially when importing JavaScript). And unless one would argue that the Promise catch function also shouldn't allow a type annotation on the error parameter, this argument seems to make very little practical sense.

I believe one of the other arguments against is that it might be confusing, as it looks like the typed exception handling you might see in other languages (e.g., Java), and folks may think the catch will only catch errors of the annotated type. I don't personally believe that's a legitimate issue, but if it really is I'd propose at least allowing a catch (err as Error) { syntax or similar as a way of emphasizing that it's a type assertion.

If nothing else at all, it seems that there should be a way to trigger a warning (similar to an implicit any warning) when using an untyped err directly within a catch block.

I do like the idea of catch (err as Error) because, damn it, if you were going to cast it anyway, maybe we should make your life a little easier while keeping it explicit.

I agree, it is possible to safely annotate the error variable in many situations. Older discussion in #8677 (comment).

It also true that it's easy to misunderstand/abuse, but then so are type annotations in general, and people just do the cast in the first line of the catch block anyway.

Jared Russell (@jaredru)

Jared Russell (@jaredru) code like

function promiseCatch() {
  rejected.catch((err: Error) => { // OK
    // Compiler error; Yay!
    console.log(err.mesage.length);
  });
}

is dangerous and misleading. It only passes the type checker because the parameter of the catch method's callback is declared to be any. At best this is a disguised type assertion.

Promise.reject(NaN).catch((e: Error) => e.message.length);

I disagree. It is no more dangerous or misleading than const foo: Foo = JSON.parse(input);, which is a very reasonable pattern. It represents our expectations and assertions about the code we're dealing with.

The irony of your example is that it throws a TypeError, which gets at my underlying point. Aside from contrived examples, the expected currency for errors is Error. A simple search through the TypeScript repo itself shows that catch (e) virtually always assumes the e to be an Error. That doesn't make it "right", of course, but it highlights the realistic expectation of a large, real-world project that (presumably) reflects an understanding of the balance between correctness and pragmatism, particularly as it relates to TypeScript.

I disagree. It is no more dangerous or misleading than const foo: Foo = JSON.parse(input);, which is a very reasonable pattern. It represents our expectations and assertions about the code we're dealing with.

I don't think that is a good pattern either.

const foo = <Foo>JSON.parse(input);

Is much clearer as to intent.

As for the example, contrived as it may be, it doesn't matter what gets thrown (TypeError or not) because it is thrown from the catch causing an unexpected failure.

Sorry, consider it a typo. <Foo>JSON.parse(s) is a common pattern but is as unsafe as .catch((e: Error) => {. Both treat an any as another type with no guarantee of correctness beyond the developer's word.

it doesn't matter what gets thrown (TypeError or not) because it is thrown from the catch causing an unexpected failure.

Of course it matters. That the runtime throws an Error for all runtime errors strengthens the position that it's reasonable to expect the argument to catch to be an Error. This expectation is common in real world codebases--including, but certainly not limited to, TypeScript's.

My 2ct: If there is any party that should be able to type the exception it should be the called function, not the caller. I've seen codebases that throw strings everywhere or nothing at all (undefined). Just declaring that the type is Error doesn't make it more type safe, because you never know what other functions the function you are calling may call into and what things those nested functions throw - Errors are not strongly typed and not part of the interface contract. Maybe you know it now but in the next patch version of some transient dependency it could change. So the only correct way to mirror the runtime JS is to start with ~~any~~unknown and narrow it down manually

if (err instanceof MyError) ... else throw err

switch (err && err.code) {
  case 'ENOENT': ...
  case 'EPERM': ...
  default: throw err
}

const isExpectedHTTPError = (err: any): err is HTTPError => err && typeof err.status === 'number'

if (isExpectedHTTPError(err)) {
  res.status(err.status).set(err.headers || {}).send(err.body || '')
} else {
  res.status(500)
}

And if the check doesn't pass, rethrow the error. If you don't and your usage of the error doesn't directly produce some kind of TypeError then you might swallow unexpected programming errors and create a debugging nightmare.

Is this more code to write? Yes. But does that justify a new feature to make the unsafe version easier to write?

My argument is for pragmatism. One of the stated non-goals of TypeScript's design is to "Apply a sound or 'provably correct' type system. Instead, strike a balance between correctness and productivity." Yes, I could get something besides an Error, but in reality--in the projects I'm working in--I won't.

As in the TypeScript codebase itself (1 2 3 4 5), it is very often safe and reasonable to assume that the thrown value is not, in fact, undefined (or null, or a string, ...) and is with almost certainty an Error. I would simply like the compiler to help me out in this case without additional code or runtime overhead.

TypeScript language is already the best I've ever worked.
If you type the catch clause this will make much better.

I would certainly love a exceptionTypeUnknown flag that makes all exception types (and Promise rejections) type unknown instead of any. That would definitely make the error handling safer as opposed to allowing any annotation. Although this could also be solved by writing a TSLint rule that forces them to always be declared unknown, if we had this annotation.

Anton Bessonov (@Bessonov)

Therefore I think that any and unknown as default are best values

Anton Bessonov (@Bessonov) I agreed with everything you said up to this point. By the points you've given, then any shouldn't be allowed either! any is even worse than MyExceptionType!

My real issue with it is its inconsistency.

If I were the TypeScript dictator, I would allow no type annotations in catch clauses. However, since any is worse than any other annotation, if you allow any I think it makes sense to allow other types too

You could just cast to Error inside the catch:

try {
  // do something
} catch (error) {
  console.error(error as Error);
}

In TypeScript 4.4+, those errors are now unknown in the catch. Or, you just type check like they do in the example here: https://devblogs.microsoft.com/typescript/announcing-typescript-4-4/#use-unknown-catch-variables

This could be really useful for test suites after 4.4 defaults to unknown. In test suites, defaulting to unknown is not appreciated as generally you know which error you expect and even if for some reason the code threw anything else, it would pop up on the test anyway.

Shinigami (@Shinigami92)

Shinigami (@Shinigami92)

How will you distinguish between the three different catch err? You see, it's impossible... 🤷
So please go to tc39 and propose something, but it's not TS related

It's possible. You can check error type inside catch and re-throw error if there was no intend to catch it. Just as suggested in other comments from @zzzzBov and from @cyraid.

So with this solution catch will work just as in most typed languages.

Actually it looks like a good solution. Or is there something wrong with it?

Bodo Graumann (@bodograumann)

This is now a real pain in typescript 4.4 with --strict, where exceptions are typed as unknown instead of any in the catch block.
I‘m not really happy with any solution I have seen

Bodo Graumann (@bodograumann) As of TypeScript 4.4 you can set useUnknownInCatchVariables=false which restores the old any behavior. It's not ideal, but nobody was complaining about this in TypeScript 3.x. (In fact the TypeScript compiler itself is currently building this way -- if you set useUnknownInCatchVariables=true in src/tsconfig-base.json, the build fails.)

A nice way to safely unwrap your unknown error is to use instanceof (as mentioned upthread)

catch (e) {
    if (e instanceof Error) {
       // type-safe, compiler can help you in this block
        console.log(e.message);
    }
    else {
        // optionally
        throw e;
    }
}

You're explicitly handling all possibilities, so it's type-safe.

I think catch variable as unknown is a good default as it encourages you to think about the values that variable can take.

It may make sense to have a tsconfig flag to allow catch (e: Error) to ease the pain for some users however.

Another (type safe) option is to allow to safely cast to something like:

} catch (e: MaybeError) {

where MaybeError is some custom type defined similar to:

type MaybeError = null | undefined | { message?: unknown; stack?: unknown; };

I.e. allow e: MaybeError if MaybeError is null, undefined, or is an object with all props being optional and of types unknown. In this case, it still allows to do lots of things (checking for props being present, checking for equality like e?.code === "some" etc.), but at the same time, does not compromise type safety.

This would work, because, when MaybeError is defined the above way, there is no JS thing which would not match it. Even null or a plain string or a number thrown will still match.

Why would anyone want to annotate something in a catch clause to 'any' or 'unknown'?! Just why? What's the gain? I mean if it wasn't annotated it's 'unknown' by default. Why would I want to get the same type with more keystrokes? What was the logic behind?

Ideally I want to annotate it as a class that extends Error, not even Error. What else could be in a catch clause, except for an Error? 🤦🏻‍♂️

Look all those issues (that I came across) about the same, nonsensical restriction; 8677, 9999, 20024 (this one), 42596

Ozan Müyesseroğlu (@ozanmuyes)

Ozan Müyesseroğlu (@ozanmuyes) You're probably new to software development. The short answer is that this would be an incorrect assumption. Try this one:

try {
    throw 'test'
} catch (e) {
    console.log(typeof e)
}

Anton Bessonov (@Bessonov)

Anton Bessonov (@Bessonov) If that is programming then yes I'm new to it. From now on I'll throw numbers and let sysadmins guess what I meant. So practical!

Literal TC39 committee members unironically throw non-Error objects in JavaScript. It's a real thing.

https://x.com/ljharb/status/1611765541085278210

Ozan Müyesseroğlu (@ozanmuyes)

Ozan Müyesseroğlu (@ozanmuyes) I'm not sure sysadmins care what you throw - unless you're throwing it at them 🤷

From a practical perspective, I'd love it if the TypeScript team would reconsider their goal of not altering runtime behavior and allow something like:

try {
    ...
} catch (e: string) {
    console.log('Handle string')
} catch (e: MySubClassError) {
    console.log('Handle MySubClassError')
}

which could be translated in something like:

try {
    ...
} catch (e) {
    if (typeof e === 'string) {
        console.log('Handle string')
    } else if (e instanceof MySubClassError) {
        console.log('Handle MySubClassError')
    } else {
        throw e
    }
}

EDIT: Nothing new, proposed already here: #20024 (comment)

I don't think I was clear — let me retry.

The ability to throw anything to break execution flow in a try block is a JavaScript thing — and I’m neutral about it. Still, I believe the majority of JS/TS developers use the catch block to handle Errors (and the like), which aligns with other programming languages. Can this be stretched? Yes — and if so, so be it. I personally don't — it's just a matter of preference.

All I really want is to get rid of this hack (e as Error) during development — and be able to type e. and have Intellisense suggest me name, message, cause?, and stack?;

// works

try {
  ...
} catch (e) {
  console.log((e as Error).message);
}

Instead being able to annotate on the catch clause;

// does not work

try {
  ...
} catch (e: Error) {
  console.log(e.message);
}

In the working snippet above, explicit casting with as is just as error-prone as plain JavaScript, and not truly type-safe. It still requires type guards to ensure runtime safety. tsc trusted me, and I let it down — that’s on me. But then, why can't I do the same thing by simply annotating? If e is unknown by default, then what’s the practical benefit of restricting annotation to only unknown or any?

TL;DR

All I really want is to get rid of this hack (e as Error) during development — and be able to type e. and have Intellisense suggest me Error's properties.

Also I believe either I shouldn't be allowed to annotate e at all — or, if I can, I should be free to use any type I want (union or not).

Navigation Menu

Repository navigation

Allow type annotation on catch clause variable #20024

63 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Allow type annotation on catch clause variable #20024

Description

Activity

DanielRosenwasser commented on Nov 15, 2017

yortus commented on Nov 15, 2017

aluanhaddad commented on Nov 20, 2017

jaredru commented on Nov 21, 2017

aluanhaddad commented on Nov 21, 2017

jaredru commented on Nov 21, 2017

felixfbecker commented on Nov 28, 2017

jaredru commented on Nov 28, 2017

lordazzi commented on Jun 1, 2018

felixfbecker commented on Aug 31, 2018

63 remaining items

vegerot commented on Sep 23, 2021

tonycoco commented on Sep 29, 2021

mckravchyk commented on Oct 25, 2021

Dador commented on Nov 3, 2021

octogonz commented on Feb 11, 2022

spephton commented on Apr 29, 2023

dimikot commented on Jan 30, 2024

ozanmuyes commented on Jul 7, 2025

Bessonov commented on Jul 7, 2025

ozanmuyes commented on Jul 7, 2025

RyanCavanaugh commented on Jul 7, 2025

Bessonov commented on Jul 7, 2025

ozanmuyes commented on Jul 7, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions