Keep an application running with a safe setting when an environment value is invalid.
Configuration parsing
Zod · Module
z.catch
.catch() supplies a fallback when schema validation fails. The fallback can be a fixed value or a function that is rerun for each failure and receives the caught error context.
How it works
Attach catch to a schema to recover from validation failure with a fallback. The fallback may be a fixed value or a function that runs whenever Zod needs to generate one; the function receives the caught error context.
Syntax
schema.catch(value)
schema.catch((ctx) => value)Parameters
| Name | Type | Description |
|---|---|---|
catchValue | unknown | (ctx: { error: ZodError }) => unknown | The value or fallback-producing function used when validation fails. |
Returns
A schema that returns its normal parsed output for valid input and the catch value for invalid input.
Key points
- Use
.catch()when invalid input should produce a fallback rather than propagate a validation error. - Call
.catch()on an existing schema and provide the fallback value as its argument. - When the input satisfies the wrapped schema, the original parsed value is returned.
- When validation fails, parsing returns the configured fallback.
- A function fallback is evaluated again for each failure, allowing dynamic fallback generation.
Common mistakes
- With codecs, catch affects decoding but not encoding.
Example: Fallback for an invalid port
import { z } from "zod";
const port = z.number().int().min(1).max(65535).catch(3000);
console.log(port.parse(8080)); // 8080
console.log(port.parse("invalid")); // 3000Valid input passes through; invalid input produces the fallback value.
When to use it
Restore a default preference when persisted data no longer matches its schema.
User preferences
Substitute a controlled value for malformed records while continuing a batch.
Data ingestion
Interview questions
QWhat does .catch() do in Zod?
.catch(value) returns the parsed value when validation succeeds and returns the supplied fallback when validation fails. For example, a number schema with .catch(42) yields the input number for valid input and 42 for invalid input.
Follow-up: How can the fallback be generated dynamically? Pass a function to .catch; Zod re-executes it whenever a catch value is needed and provides the caught error context.
QCan .catch() use a function instead of a constant?
The fallback can be a value or a function. A function is useful when the fallback must be computed per failure, and it receives context about the caught error.
Follow-up: What should be checked when using .catch() with a codec? Verify whether the operation is decoding or encoding, because catch is applied only forward.
QWhat happens on valid and invalid input?
A successful parse is returned unchanged, while a failed parse is replaced by the catch value. Thus, .catch() turns a validation failure into a successful result containing the fallback.
Follow-up: How does this differ from handling a thrown parse error? The catch schema supplies a value during parsing instead of requiring the caller to catch a ZodError.
Related
z.defaultz.prefaultz.safeParsez.codec