{ cause: err } when you do. Give each failure a class with a fixed kind, a retryable flag and a user message written in advance, keep the upstream response body out of all three, and write one log line at the edge that shows the message. Then test every classification on its own: the class, the flag, the copy, the retained cause, and the absence of the token in the log line. Do not assert on message text, and do not assume toThrow(new SomeError(...)) checks the cause, because Vitest skips the cause when the expected error has none.strict is now on by default, which makes catch-clause variables unknown, and the default target is now the current year's edition (es2025), which brings in the ErrorOptions type and switches on standard class-field semantics. A project that pins target or lib below es2022 loses the ErrorOptions type and the class-field behaviour, whatever its strict setting. Versions checked on 2026-09-30: TypeScript 7.0.2, Vitest 5.0.2, Zod 4.6.5 and typescript-eslint 8.71.0. The current Node.js releases on that date were 26.10.0 and 24.21.0 LTS; every snippet below was compiled under TypeScript 7.0.2 and every test run with Vitest 5.0.2 on Node.js 26.0.0.A customer reports that the invoice page says \"Something went wrong\". The log search turns up one line from the invoice client and one stack trace. The trace points at your own catch block. The message is fetch failed. Nothing in the log says whether the service refused the connection, timed out, or rejected the token, so nobody can say whether retrying would have helped or whether the user needs to sign in again.
Here is a client that produces exactly that, and compiles under strict:
// invoice-client.ts, before\nexport async function getInvoice(id: string, token: string) {\n try {\n const res = await fetch(`${BASE}/invoices/${id}`, {\n headers: { authorization: `Bearer ${token}` },\n signal: AbortSignal.timeout(5_000),\n });\n if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);\n return await res.json();\n } catch (e: any) {\n logger.error(`invoice ${id} failed: ${e.message}`);\n throw new Error(e.message);\n }\n}\n\n// invoice-page.ts\ngetInvoice(id, session.token).catch((e) => {\n if (e.message.includes(\"401\")) redirectToLogin();\n else if (e.message.includes(\"timeout\")) scheduleRetry();\n else toast(\"Something went wrong\");\n});Point it at a port with nothing listening and this is the whole record of what happened:
\n\nError: fetch failed\n at getInvoice (file:///app/invoice-client.mjs:13:11)\n at process.processTicksAndRejections (node:internal/process/task_queues:104:5)catch (e: any) opts out of the check that would have forced the question. Since TypeScript 4.4, useUnknownInCatchVariables types a catch-clause variable as unknown, and the TSConfig reference gives its default as \"true if strict\". The explicit : any annotation silently takes that back for this one block, and the release notes list it among the ways to \"get around\" the new errors, alongside a type assertion or turning the flag off.
throw new Error(e.message) keeps the message and nothing else. The name is gone, so a TimeoutError arrives upstream as a plain Error. The stack now starts at the throw inside the catch, line 13, instead of wherever the failure began. And the cause chain is gone: in Node, fetch reports a refused connection as a TypeError whose message is only fetch failed, with the socket error, including code: 'ECONNREFUSED', hanging off its cause. Copying the message copies the two words that carry no diagnosis. If e was not an Error at all, e.message is undefined and the new error's message is empty.
The string matching fails in a quieter way. includes(\"401\") is true for HTTP 404: invoice INV-40121 not found whenever the server echoes the ID, so a missing invoice logs the user out. includes(\"timeout\") depends on how the runtime words its message, which no specification fixes; MDN's own example for AbortSignal.timeout() branches on err.name === \"TimeoutError\" instead. And interpolating res.text() into the message sends whatever the server put in its error body into your logs, and into the toast if anyone ever renders e.message.
The mechanism is small enough to read in the specification. InstallErrorCause(obj, options) checks \"If options is an Object and ? HasProperty(options, \"cause\") is true\", then reads the value and defines it on the error as a non-enumerable data property. Two consequences follow from that wording and are easy to confirm in Node:
const err = new Error(\"outer\", { cause: undefined });\n\"cause\" in err; // true: the key was present, so the property exists\n\"cause\" in new Error(\"outer\", {}); // false\nObject.keys(new Error(\"x\", { cause: 1 })); // []: cause is not enumerable\nJSON.stringify(new Error(\"x\", { cause: 1 })); // \"{}\": no message, no causeThe first concerns presence. Passing { cause: maybeErr } where maybeErr is sometimes undefined still creates the property, so a test that asserts \"cause\" in err proves nothing about whether anything was preserved. Assert on the value.
The second is enumerability. MDN lists cause as writable, configurable and not enumerable, and an Error's message is not an own enumerable property either. A logger that serialises errors with JSON.stringify writes {} for a bare Error, or only the fields your subclass assigned, and the chain vanishes at exactly the step meant to record it. Node's util.inspect, which console.log uses, does walk the chain and prints each link under a [cause] key, which is why the same failure looks rich in a terminal and empty in the log aggregator.
MDN also makes a point about what a cause may be: \"The value of cause can be of any type\", and it shows structured data such as { code: \"NonInteger\", values: [p, q] } used deliberately as a cause. That is the tool for an HTTP failure. There is often no Error to preserve after a 401, only a status and a request ID, and a plain object carrying those is a better cause than the Response, whose body may repeat what you sent.
Custom error classes pick up the cause from super(message, options); MDN notes that the subclass constructor must pass options through for the property to be installed. The trap comes when you narrow its type. lib.es2022.error.d.ts declares cause?: unknown on Error, and redeclaring it looks harmless:
class Clobbered extends Error {\n override readonly cause?: unknown; // a field declaration: emitted as `cause;`\n constructor(message: string, options?: ErrorOptions) {\n super(message, options);\n }\n}\n\nclass Declared extends Error {\n declare readonly cause: unknown; // type information only: nothing emitted\n constructor(message: string, options?: ErrorOptions) {\n super(message, options);\n }\n}\n\nconst inner = new Error(\"inner\");\nnew Clobbered(\"x\", { cause: inner }).cause; // undefined\nnew Declared(\"x\", { cause: inner }).cause; // Error: innerBoth classes compile. The first one's cause is undefined at runtime, under tsc output and under Vitest's transform alike. With useDefineForClassFields, which the TSConfig reference says defaults to true \"if target is ES2022 or higher\", a field declaration is initialised after super() returns, and the TypeScript 3.7 release notes spell out that declarations \"are always initialized to undefined, even if they have no initializer\". The base constructor installs the cause, and the subclass's field definition overwrites it a moment later. Because TypeScript 6.0 moved the default target to es2025, projects that never touched their config now get this behaviour. The fix the same release notes give is the declare modifier, \"to indicate that a property should have no emit\".
The replacement splits the client's failures by what the caller should do next, not by HTTP status. Four kinds cover it: the request was invalid, the credentials were rejected, no answer arrived in time, and everything else. Each class fixes its user copy and its retry decision at the point where it is defined, so no caller has to reconstruct them from a message:
\n\nexport type FailureKind = \"validation\" | \"unauthorized\" | \"timeout\" | \"unknown\";\n\nexport abstract class ApiError extends Error {\n abstract readonly kind: FailureKind;\n abstract readonly retryable: boolean;\n abstract readonly userMessage: string;\n declare readonly cause: unknown; // a type annotation only: no field is emitted\n readonly correlationId: string;\n\n constructor(message: string, correlationId: string, options?: ErrorOptions) {\n super(message, options);\n this.name = new.target.name;\n this.correlationId = correlationId;\n }\n}\n\nexport class ValidationError extends ApiError {\n readonly kind = \"validation\";\n readonly retryable = false;\n readonly userMessage = \"Some details were not accepted. Check the highlighted fields.\";\n readonly fields: readonly string[];\n\n constructor(fields: readonly string[], correlationId: string, options?: ErrorOptions) {\n super(`request rejected for fields: ${fields.join(\", \") || \"(none listed)\"}`, correlationId, options);\n this.fields = fields;\n }\n}\n\nexport class UnauthorizedError extends ApiError {\n readonly kind = \"unauthorized\";\n readonly retryable = false;\n readonly userMessage = \"Your session has expired. Sign in again to continue.\";\n}\n\nexport class RequestTimeoutError extends ApiError {\n readonly kind = \"timeout\";\n readonly retryable = true;\n readonly userMessage = \"The service is slow to respond. Try again in a moment.\";\n}\n\nexport class UnknownApiError extends ApiError {\n readonly kind = \"unknown\";\n readonly retryable: boolean;\n\n constructor(message: string, correlationId: string, retryable: boolean, options?: ErrorOptions) {\n super(message, correlationId, options);\n this.retryable = retryable;\n }\n\n get userMessage(): string {\n return `Something went wrong on our side. Reference: ${this.correlationId}`;\n }\n}\n\nexport function errorName(value: unknown): string | undefined {\n return typeof value === \"object\" && value !== null && \"name\" in value && typeof value.name === \"string\"\n ? value.name\n : undefined;\n}new.target.name sets name to the concrete subclass, so RequestTimeoutError prints as itself in a stack trace without each class repeating the assignment. errorName is a structural check rather than instanceof DOMException, for reasons the FAQ below gets into. The client decides which class applies:
import * as z from \"zod\";\nimport {\n type ApiError,\n RequestTimeoutError,\n UnauthorizedError,\n UnknownApiError,\n ValidationError,\n errorName,\n} from \"./errors\";\n\nexport interface InvoiceClientOptions {\n baseUrl: string;\n token: string;\n timeoutMs?: number;\n fetchImpl?: typeof fetch;\n correlationId?: () => string;\n}\n\nexport async function getInvoice(id: string, opts: InvoiceClientOptions): Promise<unknown> {\n const correlationId = (opts.correlationId ?? (() => crypto.randomUUID()))();\n const fetchImpl = opts.fetchImpl ?? fetch;\n\n let res: Response;\n try {\n res = await fetchImpl(`${opts.baseUrl}/invoices/${encodeURIComponent(id)}`, {\n headers: { authorization: `Bearer ${opts.token}`, \"x-correlation-id\": correlationId },\n signal: AbortSignal.timeout(opts.timeoutMs ?? 5_000),\n });\n } catch (err) {\n throw transportFailure(err, correlationId);\n }\n\n if (res.ok) return res.json(); // then parse it at the boundary\n throw await responseFailure(res, correlationId);\n}\n\nfunction transportFailure(err: unknown, correlationId: string): unknown {\n const name = errorName(err);\n if (name === \"AbortError\") return err; // the caller cancelled: not ours to classify\n if (name === \"TimeoutError\") {\n return new RequestTimeoutError(\"no response before the deadline\", correlationId, { cause: err });\n }\n return new UnknownApiError(\"request did not complete\", correlationId, true, { cause: err });\n}\n\nconst ProblemBody = z.object({ errors: z.array(z.object({ field: z.string() })) });\n\nasync function responseFailure(res: Response, correlationId: string): Promise<ApiError> {\n // Metadata only. The body can echo what was sent, so it never becomes the cause.\n const upstream = { status: res.status, upstreamRequestId: res.headers.get(\"x-request-id\") };\n\n if (res.status === 401) {\n return new UnauthorizedError(`upstream answered ${res.status}`, correlationId, { cause: upstream });\n }\n if (res.status === 400 || res.status === 422) {\n const parsed = ProblemBody.safeParse(await res.json().catch(() => null));\n const fields = parsed.success ? parsed.data.errors.map((e) => e.field) : [];\n return new ValidationError(fields, correlationId, { cause: { ...upstream, fields } });\n }\n return new UnknownApiError(`upstream answered ${res.status}`, correlationId, res.status >= 500, {\n cause: upstream,\n });\n}The 401 branch keeps only the status and the upstream request ID as its cause, which is all an engineer needs to find the matching entry in the provider's logs. The 422 branch reads the body once, through a schema, to extract field names and nothing else; the part-one article on validating payloads at the runtime boundary covers what to do with the successful body and how to summarise a rejected one safely. An AbortError is passed through untouched, because the caller cancelled on purpose and a user-facing \"slow service\" message would be wrong.
The retry flag on UnknownApiError is true for transport failures and 5xx answers and false for anything else in the 4xx range. That is defensible for a GET. For a request with side effects, a transport failure after the bytes were sent is ambiguous, and the flag needs the reasoning in the idempotency and retry article before it can be true.
The table the tests will pin down:
\n\n| Input failure | Class | User copy | Cause kept | Retry |
|---|---|---|---|---|
| 422 with field errors | ValidationError | Check the highlighted fields | status, request ID, field names | no |
| 401 | UnauthorizedError | Session expired, sign in | status, request ID | no |
AbortSignal.timeout() fires | RequestTimeoutError | Slow to respond, try again | the TimeoutError DOMException | yes |
Connection refused (TypeError: fetch failed) | UnknownApiError | Our side, with a reference | the TypeError and its socket error | yes |
| 404, 409, other 4xx | UnknownApiError | Our side, with a reference | status, request ID | no |
| Caller aborts | none, rethrown as is | none | not wrapped | no |
The old client logged inside its catch and then threw, and the page probably logged again: two lines per failure, neither complete. Move logging to the single place that also decides what the user sees, and have every layer below it throw without logging:
\n\nimport { ApiError, type FailureKind, errorName } from \"./errors\";\n\nexport interface FailureLogLine {\n event: \"api_client_failure\";\n error: string;\n kind: FailureKind;\n message: string;\n correlationId: string;\n retryable: boolean;\n causes: string[];\n}\n\n// Names, codes and statuses only. A cause's message can carry a URL, a query\n// string or an echoed field value, so messages below the top level are dropped.\nexport function causeChain(err: Error, limit = 5): string[] {\n const chain: string[] = [];\n let current: unknown = err.cause;\n while (current !== undefined && chain.length < limit) {\n if (typeof current !== \"object\" || current === null) {\n chain.push(typeof current);\n break;\n }\n const parts = [errorName(current) ?? \"data\"];\n if (\"code\" in current && typeof current.code === \"string\") parts.push(current.code);\n if (\"status\" in current && typeof current.status === \"number\") parts.push(String(current.status));\n chain.push(parts.join(\":\"));\n current = \"cause\" in current ? current.cause : undefined;\n }\n return chain;\n}\n\nexport function toLogLine(err: ApiError): FailureLogLine {\n return {\n event: \"api_client_failure\",\n error: err.name,\n kind: err.kind,\n message: err.message,\n correlationId: err.correlationId,\n retryable: err.retryable,\n causes: causeChain(err),\n };\n}\n\nexport function present(err: unknown, log: (line: FailureLogLine) => void) {\n if (err instanceof ApiError) {\n log(toLogLine(err));\n return { text: err.userMessage, canRetry: err.retryable };\n }\n throw err; // not a client failure: let it reach the framework's handler\n}causeChain walks the chain by hand because neither of the built-in renderings is safe to ship. JSON.stringify drops the chain, and util.inspect prints it along with every own enumerable property of every link, including the peer address on a socket error and anything a well-meaning colleague attaches as err.request. Here is the same refused connection through the new client, first as console.log renders it, then as the log line:
UnknownApiError: request did not complete\n at transportFailure (/app/src/client.ts:43:10)\n at getInvoice (/app/src/client.ts:30:11) {\n correlationId: 'corr-7',\n kind: 'unknown',\n retryable: true,\n [cause]: [TypeError: fetch failed] {\n [cause]: Error: connect ECONNREFUSED 127.0.0.1:59998\n at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1705:16) {\n errno: -61,\n code: 'ECONNREFUSED',\n syscall: 'connect',\n address: '127.0.0.1',\n port: 59998\n }\n }\n}{\"event\":\"api_client_failure\",\"error\":\"UnknownApiError\",\"kind\":\"unknown\",\"message\":\"request did not complete\",\"correlationId\":\"corr-7\",\"retryable\":true,\"causes\":[\"TypeError\",\"Error:ECONNREFUSED\"]}The first is for a terminal. The second is what you can afford to keep for months where many people can query it: the kind, the correlation ID support can quote from the user message, and a chain that still says ECONNREFUSED without naming the host.
Each test drives one row of the table through the real getInvoice, with a stubbed fetchImpl, and asserts the four properties the table promises rather than a message:
import { describe, expect, test, vi } from \"vitest\";\nimport { getInvoice } from \"./client\";\nimport { RequestTimeoutError, UnauthorizedError, UnknownApiError, ValidationError } from \"./errors\";\nimport { present, toLogLine } from \"./log\";\n\nconst TOKEN = \"tok_live_8f2c1d9a\";\nconst base = { baseUrl: \"https://billing.example.test\", token: TOKEN, correlationId: () => \"corr-7\" };\n\nconst answer = (status: number, body: unknown = {}, headers: Record<string, string> = {}) =>\n vi.fn<typeof fetch>(async () => Response.json(body, { status, headers }));\n\nasync function failureOf(work: Promise<unknown>): Promise<unknown> {\n try {\n await work;\n } catch (err) {\n return err;\n }\n throw new Error(\"expected the call to reject\");\n}\n\ndescribe(\"getInvoice failure classification\", () => {\n test(\"422 becomes a non-retryable ValidationError naming the fields\", async () => {\n const fetchImpl = answer(422, { errors: [{ field: \"currency\" }], echoed: { email: \"asha@example.test\" } });\n const err = await failureOf(getInvoice(\"INV-40121\", { ...base, fetchImpl }));\n\n expect.assert(err instanceof ValidationError);\n expect(err).toMatchObject({ kind: \"validation\", retryable: false, fields: [\"currency\"], correlationId: \"corr-7\" });\n expect(err.cause).toEqual({ status: 422, upstreamRequestId: null, fields: [\"currency\"] });\n expect(JSON.stringify(err.cause)).not.toContain(\"asha@example.test\");\n });\n\n test(\"401 becomes UnauthorizedError with only upstream metadata as its cause\", async () => {\n const fetchImpl = answer(401, { detail: \"token expired\" }, { \"x-request-id\": \"up-991\" });\n const err = await failureOf(getInvoice(\"INV-1\", { ...base, fetchImpl }));\n\n expect.assert(err instanceof UnauthorizedError);\n expect(err.retryable).toBe(false);\n expect(err.userMessage).toBe(\"Your session has expired. Sign in again to continue.\");\n expect(err.cause).toEqual({ status: 401, upstreamRequestId: \"up-991\" });\n });\n\n test(\"a deadline becomes a retryable RequestTimeoutError that keeps the DOMException\", async () => {\n const hang = vi.fn<typeof fetch>(\n (_url, init) =>\n new Promise((_resolve, reject) => {\n init?.signal?.addEventListener(\"abort\", () => reject(init.signal?.reason));\n }),\n );\n const err = await failureOf(getInvoice(\"INV-1\", { ...base, fetchImpl: hang, timeoutMs: 20 }));\n\n expect.assert(err instanceof RequestTimeoutError);\n expect(err.retryable).toBe(true);\n expect(err.cause).toBeInstanceOf(DOMException);\n expect(err.cause).toMatchObject({ name: \"TimeoutError\" });\n });\n\n test(\"a transport TypeError becomes UnknownApiError and is kept by reference\", async () => {\n const refused = new TypeError(\"fetch failed\", { cause: { code: \"ECONNREFUSED\" } });\n const fetchImpl = vi.fn<typeof fetch>(async () => {\n throw refused;\n });\n const err = await failureOf(getInvoice(\"INV-1\", { ...base, fetchImpl }));\n\n expect.assert(err instanceof UnknownApiError);\n expect(err.retryable).toBe(true);\n expect(err.cause).toBe(refused);\n expect(err.userMessage).toContain(\"corr-7\");\n });\n\n test(\"a 404 for an id containing 401 is not an auth failure\", async () => {\n const err = await failureOf(getInvoice(\"INV-40121\", { ...base, fetchImpl: answer(404) }));\n\n expect.assert(err instanceof UnknownApiError);\n expect(err.retryable).toBe(false);\n expect(err.cause).toEqual({ status: 404, upstreamRequestId: null });\n });\n});\n\ndescribe(\"the logging boundary\", () => {\n test(\"one line per failure, with the chain and without the token\", async () => {\n const lines: unknown[] = [];\n const err = await failureOf(getInvoice(\"INV-1\", { ...base, fetchImpl: answer(401, { token: TOKEN }) }));\n\n const shown = present(err, (line) => lines.push(line));\n\n expect(shown).toEqual({ text: \"Your session has expired. Sign in again to continue.\", canRetry: false });\n expect(lines).toEqual([\n expect.objectContaining({ error: \"UnauthorizedError\", correlationId: \"corr-7\", causes: [\"data:401\"] }),\n ]);\n expect(JSON.stringify(lines)).not.toContain(TOKEN);\n });\n\n test(\"the chain reaches the socket error under fetch's TypeError\", () => {\n const socket = Object.assign(new Error(\"connect ECONNREFUSED 10.0.0.4:443\"), { code: \"ECONNREFUSED\" });\n const err = new UnknownApiError(\"request did not complete\", \"corr-8\", true, {\n cause: new TypeError(\"fetch failed\", { cause: socket }),\n });\n\n expect(toLogLine(err).causes).toEqual([\"TypeError\", \"Error:ECONNREFUSED\"]);\n expect(JSON.stringify(toLogLine(err))).not.toContain(\"10.0.0.4\");\n });\n\n test(\"anything that is not a client failure is rethrown untouched\", () => {\n const bug = new RangeError(\"index out of bounds\");\n expect(() => present(bug, () => {})).toThrow(bug);\n });\n});A few choices in that file are deliberate.
\n\nfailureOf uses try/catch rather than .catch((e) => e). useUnknownInCatchVariables covers catch clauses and nothing else. typescript-eslint's documentation for use-unknown-in-catch-callback-variable says that a Promise's catch() callback parameter \"will always have the type any\", and the compiler agrees:
try {\n await getInvoice(id, opts);\n} catch (err) {\n err.message; // error TS18046: 'err' is of type 'unknown'.\n}\n\ngetInvoice(id, opts).catch((err) => err.status.code); // compiles: err is anyThe lint rule is in strict-type-checked, not the recommended set, and needs type information. Without it, the callback form is where any gets back into error handling.
expect.assert(err instanceof ValidationError) fails the test and narrows the type in one line, so the assertions after it read typed properties without a cast.
The timeout test does not fake the signal. It hands the client a fetch that never settles and lets AbortSignal.timeout(20) fire for real, so the cause under test is the DOMException the platform creates. MDN documents that the signal's reason is \"a TimeoutError DOMException\", and asserting toBeInstanceOf(DOMException) together with the name pins both halves.
The transport test uses toBe on the cause, not toEqual. The requirement is that the original object survives, and reference identity is the only assertion that cannot pass on a lookalike.
The 404 test uses an ID containing 401, so it fails if anyone reintroduces message matching.
The token assertion runs on the serialised log line, because that is the artefact that leaves the process.
\n\nThe shortest-looking test for this client is expect(fn).toThrow(new UnauthorizedError(...)). Vitest's toThrow compares any non-string, non-RegExp argument \"using deep equality (similar to toEqual)\", and the toEqual documentation carries a warning: for Errors, name, message and cause are compared, but \"For Error.cause, the comparison is done asymmetrically\". An expected error with no cause matches an actual error with any cause, or none:
const lost = () => {\n throw new UnauthorizedError(\"upstream answered 401\", \"corr-7\"); // cause dropped\n};\n\n// Passes. The expected error has no cause, so the actual one's cause is not compared.\nexpect(lost).toThrow(new UnauthorizedError(\"upstream answered 401\", \"corr-7\"));\n\n// Fails, as it should: the cause is part of what is being asserted.\nexpect(lost).toThrow(expect.objectContaining({ cause: expect.objectContaining({ status: 401 }) }));Both halves were run against Vitest 5.0.2: the first passes on an error whose cause was dropped, the second fails on it. A test written before you added causes keeps passing after someone removes them again. Assert the cause explicitly, with objectContaining for structured data or toBe for an original error.
Every class has to be kept accurate. A provider that starts answering 403 for expired sessions lands in UnknownApiError with retry off, and the only symptom is tickets quoting a reference. A growing unknown share in the log lines is the signal that a new class is due.
This is also the place where a language model is useful and where it must not have the last word. Handed a week of unknown log lines, which carry names, codes and statuses rather than bodies, a model will cluster them into plausible categories quickly. Whether a cluster is retryable, and what the user is told, is still your decision, and each proposed class gets a row in the table and a test before it ships.
Skip all of this in a CLI or a build script, where the printed stack trace is the interface and its reader is the person who can fix it. And do not wrap an error you cannot classify better than it already is; rethrowing the original is correct when the wrapper would add nothing but a new message.
\n\nNot yet, for browser code. Error.isError() is in the current ECMAScript draft and works across realms where instanceof Error does not, but MDN marks it \"Limited availability\", not Baseline. MDN's compatibility data adds the detail that matters here: Safari 18.4 ships it as a partial implementation that \"returns false for DOMException instances\", which is exactly the class a timeout produces. Node.js has the full behaviour from 24.3.0. TypeScript only declares it in lib.esnext.error, so you would also need esnext in lib. A structural check on name works in every runtime today.
When there were several independent failures. MDN draws the line clearly: cause \"represents a single failing site\", with the wrapper only adding context, while AggregateError represents \"a collection of multiple, unrelated errors that occurred during the same operation\". Fanning a request out to three mirrors and losing all three is an AggregateError. A 401 wrapped in UnauthorizedError is one failure with context, so it is a cause.
For a single-language application it is the simplest arrangement that keeps copy and retry policy next to each other and under test. If the interface is translated, keep kind on the error and map it to a translation key at the presentation edge instead; the tests then assert the key, and the classification tests stay the same.
Find the three habits from the start of this article in your codebase:
\n\n# Catch variables that opt out of unknown, and rethrows that drop the original\ngrep -rnE --include='*.ts' --include='*.tsx' \\\n -e 'catch \\((\\w+): any\\)' \\\n -e 'new \\w*Error\\(\\w+\\.message\\)' \\\n -e '\\.message\\.(includes|startsWith|match)\\(' srcPick the API client whose failures reach users most often. Replace its catch-all with the four classes, pass every original as cause, and put the log call at the one place that renders the message. Grep the same client for readonly cause without declare in front of it. If your lint already runs with type information, add @typescript-eslint/use-unknown-in-catch-callback-variable to catch the promise-callback form the compiler lets through.
The evidence to keep is the failure table above filled in for that client, one test per row, and a captured log line for each kind, committed next to the tests. Diffing a captured line before and after a change in the JSON Diff tool shows at a glance whether a field that should never be logged has started to appear.
\n\ncause is writable, configurable and not enumerable; that \"the value of cause can be of any type\", with structured data shown as a deliberate cause; that cause \"represents a single failing site\" while AggregateError and SuppressedError represent multiple; and that the feature has been Baseline across browsers since September 2021.options to super() for the base constructor to install cause, that passing the original as cause means \"the original error and stack trace are available to higher-level try/catch blocks\", and that libraries should prefer cause over asking consumers to parse messages.Error.isError() is a branded check that accepts errors from other realms where instanceof Error does not, that it returns true for DOMException instances, and that it is \"Limited availability\", not Baseline.Error.isError: Chrome 134, Firefox 138, full support in Node.js from 24.3.0, and Safari 18.4 as a partial implementation that \"returns false for DOMException instances\".cause only when HasProperty(options, \"cause\") is true, as a non-enumerable data property, which is why { cause: undefined } still creates the property; and the steps of Error.isError, which test for the [[ErrorData]] internal slot.reason is set to that exception, and the documented pattern of branching on err.name (TimeoutError versus AbortError) rather than on message text.AbortError DOMException when aborted and with a TypeError for network errors and invalid requests, the two transport shapes the client classifies.fetch() \"is based upon undici\" and that AbortSignal.timeout(delay) returns a signal aborted after the delay. The TypeError: fetch failed shape with the socket error, including code, under cause, and util.inspect rendering each link as [cause], were observed by running Node.js 26.0.0.unknown, that its default is \"true if strict; false otherwise\", and that it was released in TypeScript 4.4.useUnknownInCatchVariables under strict, and that an explicit : any on the catch variable is one of the listed ways to \"get around\" the resulting errors.strict is now true by default and that target defaults to the most recent supported edition, \"right now, that target is es2025\".super(), and that the declare modifier marks \"a property should have no emit\". The article confirmed the effect on cause with TypeScript 7.0.2 and Vitest 5.0.2.ErrorOptions and cause?: unknown on Error are declared in the es2022 library, so the two-argument constructor is a type error with an older lib; confirmed with TypeScript 7.0.2, where --lib es2021 reports \"Expected 0-1 arguments, but got 2\", and that Error.isError is declared only in lib.esnext.error.d.ts.toThrow compares a non-string, non-RegExp argument \"using deep equality (similar to toEqual)\"; that toEqual compares name, message and cause on errors but compares cause \"asymmetrically\"; that rejects unwraps a rejected promise for matchers; and expect.assert for narrowing. The asymmetric pass on a dropped cause was confirmed with Vitest 5.0.2.Promise.prototype.catch() \"is not affected by the useUnknownInCatchVariables compiler option\" and its callback parameter \"will always have the type any\", that the rule is enabled by strict-type-checked, and that it requires type information.safeParse returns a result object that \"is a discriminated union\" instead of throwing, used to read field names from a 422 body without trusting its shape.