TypeScript Try Catch: Error Types and Custom Errors

TypeScript uses JavaScript's try, catch, finally and throw. The TypeScript-specific part is the catch variable: with strict on, it has type unknown, so you check what was thrown before using it.

function parsePort(text: string): number {
    const port = Number(text);
    if (!Number.isInteger(port) || port < 1 || port > 65535) {
        throw new RangeError(`invalid port: "${text}"`);
    }
    return port;
}

try {
    console.log(parsePort("8080")); // 8080
    console.log(parsePort("http")); // throws
} catch (e) {
    // e: unknown
    if (e instanceof Error) {
        console.log(`${e.name}: ${e.message}`); // RangeError: invalid port: "http"
    }
} finally {
    console.log("done");
}

The runtime side (how the stack unwinds, which built-in error types exist) is covered in JavaScript try/catch.

Why the catch Variable Is unknown

JavaScript can throw anything: an Error, a string, a number, undefined, an object from a library. TypeScript cannot know which, so under strict (the useUnknownInCatchVariables flag) the variable is unknown and you must narrow it before use:

// This does not compile: e is unknown, so e.message is not allowed.
try {
    JSON.parse("{ broken");
} catch (e) {
    console.log("parse failed:", e.message);
}

index.ts(5,34): error TS18046: 'e' is of type 'unknown'.

Without strict, e is any and the same code compiles, then goes wrong at runtime when a string is thrown: e.message is undefined, and anything deeper, such as e.message.length, throws a TypeError. You cannot annotate your way out either: catch (e: Error) is error TS1196 (Catch clause variable type annotation must be 'any' or 'unknown' if specified).

Narrowing the Error

instanceof Error covers everything built on Error, including TypeError, SyntaxError, RangeError and your own subclasses. For anything else, fall back to converting the value to a string. A small helper keeps call sites short:

function toError(value: unknown): Error {
    if (value instanceof Error) return value;
    if (typeof value === "string") return new Error(value);
    return new Error(`non-error thrown: ${JSON.stringify(value)}`);
}

const throwers: Array<() => void> = [
    () => JSON.parse("{"),
    () => { throw "plain string"; },
    () => { throw { code: 42 }; },
];

for (const run of throwers) {
    try {
        run();
    } catch (e) {
        const err = toError(e);
        console.log(err.constructor.name, "|", err.message);
    }
}
// SyntaxError | Expected property name or '}' in JSON at position 1 (line 1 column 2)
// Error | plain string
// Error | non-error thrown: {"code":42}

A catch that only handles some errors should rethrow the rest: if (!(e instanceof ValidationError)) throw e;. Swallowing unknown errors hides real bugs.

Throwing Errors

throw accepts any expression, and TypeScript does not restrict it. Throw Error objects anyway: they carry a stack trace, and every instanceof Error check in the codebase depends on it.

A function that always throws has the return type never, which TypeScript uses for narrowing after the call:

function fail(message: string): never {
    throw new Error(message);
}

function getEnv(env: Record<string, string | undefined>, key: string): string {
    const value = env[key];
    if (value === undefined) fail(`missing ${key}`);
    return value; // value: string, because fail() never returns
}

const env = { HOME: "/home/ada" };
console.log(getEnv(env, "HOME")); // /home/ada
try {
    getEnv(env, "PORT");
} catch (e) {
    if (e instanceof Error) console.log(e.message); // missing PORT
}

Since ES2022, Error takes a second argument with a cause, which chains a low-level error to the one you throw: throw new Error("could not load settings", { cause: e }). The caller can read err.cause (typed unknown).

Custom Error Classes

A subclass of Error lets callers tell failures apart with instanceof and carry extra data. Set name, because the inherited one is "Error" and it appears in logs and in String(err):

class HttpError extends Error {
    override name = "HttpError";

    constructor(readonly status: number, message: string, options?: ErrorOptions) {
        super(message, options);
    }
}

class NotFoundError extends HttpError {
    override name = "NotFoundError";

    constructor(resource: string) {
        super(404, `${resource} not found`);
    }
}

function handle(e: unknown): string {
    if (e instanceof NotFoundError) return `404 page for: ${e.message}`;
    if (e instanceof HttpError) return `HTTP ${e.status}: ${e.message}`;
    if (e instanceof Error) return `unexpected: ${e.message}`;
    return "unknown failure";
}

console.log(handle(new NotFoundError("user 7"))); // 404 page for: user 7 not found
console.log(handle(new HttpError(503, "maintenance"))); // HTTP 503: maintenance
console.log(handle(new TypeError("oops")));        // unexpected: oops

const wrapped = new HttpError(500, "db down", { cause: new Error("timeout") });
const cause = wrapped.cause; // unknown
console.log(String(wrapped), "| cause:", cause instanceof Error ? cause.message : cause);
// HttpError: db down | cause: timeout

Check the most specific class first, since a NotFoundError is also an HttpError. The override modifier is optional here unless noImplicitOverride is on.

Older guides add Object.setPrototypeOf(this, new.target.prototype) to every error constructor. That was needed when compiling classes down to ES5 functions, where instanceof broke for Error subclasses. TypeScript 7 no longer supports target: "es5" (it reports TS5108: Option 'target=ES5' has been removed), and with ES2015 or later the native class ... extends Error works, as above.

The Result Pattern

TypeScript does not track which errors a function can throw, so nothing reminds callers to handle them. For failures that are expected (invalid input, a missing record), returning a value that says "success or failure" puts the error into the type system:

type Result<T, E = string> =
    | { ok: true; value: T }
    | { ok: false; error: E };

function parseAge(input: string): Result<number> {
    const n = Number(input);
    if (!Number.isInteger(n)) return { ok: false, error: `"${input}" is not a whole number` };
    if (n < 0 || n > 150) return { ok: false, error: `${n} is out of range` };
    return { ok: true, value: n };
}

for (const input of ["36", "abc", "200"]) {
    const r = parseAge(input);
    if (r.ok) {
        console.log("age:", r.value + 1); // r.value only exists when ok is true
    } else {
        console.log("error:", r.error);
    }
}
// age: 37
// error: "abc" is not a whole number
// error: 200 is out of range

Reading r.value before checking r.ok is a compile error, which is the point. Use exceptions for the unexpected (bugs, a broken connection) and Result values for outcomes the caller must decide about.

Errors in Async Code

A rejected promise becomes a thrown error at the await, so try/catch around await works the same way, and the variable is again unknown. The one difference is .catch() on a promise: its callback parameter is typed any, not unknown, so annotate it yourself (.catch((e: unknown) => ...)). See async/await for examples.

Common Mistakes

• Reading e.message without narrowing. Under strict it does not compile; without strict it breaks on non-Error throws.
• Catching everything and continuing. Handle the errors you expect and rethrow the rest.
• Forgetting name on custom errors. Logs then say Error for all of them.
• Throwing strings. throw "failed" has no stack trace and fails instanceof Error checks.