Impossible branches
Model an impossible branch in a union or conditional schema.
Zod · Module
z.never
z.never() creates a Zod schema that rejects every input and infers the TypeScript type never. Use it to model an impossible schema branch.
How it works
z.never() creates a schema whose inferred TypeScript type is never and whose validation always fails. It is useful when a schema branch must be impossible; unlike z.NEVER, which is a special transform-return value, this is a schema factory.
Syntax
z.never()Returns
A Zod schema that accepts no values and infers the TypeScript type never.
Key points
- The schema rejects every possible input.
- Its inferred TypeScript output type is
never. - It represents an empty set of valid runtime values.
- Create it by calling the zero-argument
z.never()factory. - The related
z.NEVERvalue is used in transforms, not as a replacement for the schema factory.
Common mistakes
- Every input fails validation, so this schema cannot accept even values that are otherwise valid for another primitive schema.
Example: Reject every value
import { z } from "zod";
const NoValue = z.never();
console.log(NoValue.safeParse("anything").success); // false
Creates a schema that rejects every input.
When to use it
Reject all values
Explicitly prevent all runtime values from satisfying a placeholder schema.
Type-level impossibility
Represent an uninhabitable TypeScript output type alongside runtime validation.
Interview questions
QWhat does z.never() validate?
z.never() returns a schema that accepts no values. Its inferred TypeScript type is never, making it suitable for representing an impossible branch.
Follow-up: How does it differ from z.NEVER? z.never() is a schema, while z.NEVER is a special value that can be returned from a transform without changing the inferred output type.
QWhen would you use a never schema?
Use z.never() when a schema branch should be impossible and must reject all runtime inputs. Parsing against it fails regardless of the supplied value.
Follow-up: What runtime behavior should callers expect? They should handle a failed parse or use a safe parsing method because successful parsing cannot occur.
QWhat are the syntax and inferred type of z.never()?
The declaration is z.never(), and the documentation shows its inferred type as never. It is distinct from ordinary schemas because its accepted set is empty.
Follow-up: Can it produce a successful parsed value? No; the documented contract is that no value passes validation.
Related
z.NEVERz.any()z.unknown()