is-network-error

is-network-error is a tiny, dependency-free utility from Sindre Sorhus that answers one narrow but persistent question: was this error actually a network failure? The Fetch API’s network-error behavior was never standardized, so Chrome, Firefox, Safari, Bun, Deno, and Node’s Undici each throw a different flavor of TypeError with a different message. This package encodes those differences into a single type-guard function so application code can branch on real connectivity failures without accidentally swallowing unrelated fetch errors.

It ships as a single ESM export with full TypeScript typings, has zero runtime dependencies, and is small enough to embed anywhere fetch-based error handling is needed, from browser apps to serverless workers. It’s already used internally by other Sindre Sorhus packages such as p-retry to decide when a failed request is worth retrying.

What You Get

• Type-guard function - isNetworkError(value) narrows unknown to TypeError when it detects a network failure.
• Cross-runtime coverage - Recognizes network error messages from Chrome, Firefox, Safari 16+/17+, Bun, Deno, Undici (Node.js), and Cloudflare Workers.
• Zero dependencies - A single small ESM file with no runtime dependencies to audit or update.
• Full TypeScript types - Ships index.d.ts with a documented type predicate and matching test-d.ts type tests.

Common Use Cases

• Retry logic - Retry a fetch call only when the failure was a genuine network error, not an application-level error.
• Offline fallbacks - Fall back to cached or local data specifically when connectivity is lost.
• Error reporting filters - Exclude expected network blips from error-tracking pipelines like Sentry.
• Cross-browser fetch wrappers - Build a fetch wrapper that behaves consistently despite differing browser error messages.

Under The Hood

Architecture The package is a single exported function in index.js with no internal modules or layers: it validates that the input is an Error named TypeError with a string message, then runs the message (and, for Safari’s ambiguous case, the stack property) through a short sequence of pattern checks, an exact-match Set lookup for standard runtime strings, and a couple of startsWith/endsWith checks for messages that embed a hostname. Data flow is a straight function call with no shared state, no I/O, and no async behavior, so there is nothing to break beyond the pattern list itself going stale as runtimes change their wording.

Tech Stack Pure JavaScript (ESM, type: module) with a companion index.d.ts for TypeScript consumers; there is no build step since the published files are the source files. Node.js engines are constrained to >=16. Development tooling is xo for linting, ava for the test runner, and tsd for type-level testing, wired together behind a single npm test script; there is no bundler, framework, or database involved anywhere in the package.

Code Quality test.js exercises the function against real and constructed errors for every supported runtime (Chrome, Firefox, Safari with and without a stack, Bun, Deno, Undici, Cloudflare Workers) plus explicit negative cases (wrong error name, non-Error values, unrelated TypeErrors), giving the small surface area comprehensive coverage. Linting is enforced via xo (an opinionated ESLint config) and type correctness is checked separately via tsd, so both runtime behavior and the public type signature are verified on every test run. Naming is plain and self-documenting, and the code favors early-return validation over nested conditionals.

What Makes It Unique The package doesn’t introduce a new abstraction; its value is in having already done the tedious cross-runtime research into how each JavaScript environment phrases a Fetch network failure, including tricky edge cases like Safari 17 using the same generic message for network and non-network errors (distinguished only by the presence of a stack trace) and Sentry’s error-wrapping behavior. That accumulated knowledge is what would otherwise be duplicated and get subtly wrong in every project that needs it.