Handling Zod Errors

Purpose

Comprehensive guide to error handling in Zod v4, covering the unified error API, custom error messages, error formatting, and integration with UI frameworks.

Unified Error API

Overview

Zod v4 unified all error customization under a single error parameter, replacing multiple deprecated parameters.

v3 (deprecated):

typescript

z.string({ message: "Required" });
z.string({ invalid_type_error: "Must be string" });
z.string({ required_error: "Field required" });
z.object({}, { errorMap: customMap });

v4 (unified):

typescript

z.string({ error: "Required" });
z.string({ error: "Must be string" });
z.string({ error: "Field required" });
z.object({}, { error: customMap });

Error Parameter Types

String messages:

typescript

z.string({ error: "This field is required" });
z.email({ error: "Please enter a valid email address" });
z.number({ error: "Must be a number" }).min(0, {
  error: "Must be positive"
});

Error map functions:

typescript

const customErrorMap: ZodErrorMap = (issue, ctx) => {
  if (issue.code === z.ZodIssueCode.invalid_type) {
    return { message: `Expected ${issue.expected}, got ${issue.received}` };
  }
  return { message: ctx.defaultError };
};

z.string({ error: customErrorMap });

SafeParse Pattern

Best Practice

Always use safeParse instead of parse wrapped in try/catch:

Anti-pattern:

typescript

try {
  const data = schema.parse(input);
  return data;
} catch (error) {
  console.error(error);
  return null;
}

Best practice:

typescript

const result = schema.safeParse(input);
if (!result.success) {
  console.error(result.error);
  return null;
}
return result.data;

Benefits:

No exception overhead (better performance)
Type-safe discriminated union
More readable control flow
Explicit error handling

Type Inference

typescript

const result = schema.safeParse(input);

if (result.success) {
  const data: z.infer<typeof schema> = result.data;
} else {
  const error: z.ZodError = result.error;
}

Error Formatting

Flatten Errors

Convert nested error structure to flat format:

typescript

const userSchema = z.object({
  email: z.email(),
  age: z.number().min(18)
});

const result = userSchema.safeParse({
  email: 'invalid',
  age: 10
});

if (!result.success) {
  const flattened = result.error.flatten();
  console.log(flattened.fieldErrors);
}

Output:

typescript

{
  email: ["Invalid email"],
  age: ["Number must be greater than or equal to 18"]
}

Format for Forms

React Hook Form integration:

typescript

const result = formSchema.safeParse(data);

if (!result.success) {
  const errors = result.error.flatten().fieldErrors;

  return {
    errors: {
      email: errors.email?.[0],
      password: errors.password?.[0]
    }
  };
}

Format for API Responses

typescript

const result = schema.safeParse(data);

if (!result.success) {
  return {
    success: false,
    errors: result.error.flatten().fieldErrors
  };
}

return {
  success: true,
  data: result.data
};

Custom Error Messages

Field-Level Errors

typescript

const userSchema = z.object({
  email: z.email({
    error: "Please enter a valid email address"
  }),
  password: z.string({
    error: "Password is required"
  }).min(8, {
    error: "Password must be at least 8 characters"
  }),
  age: z.number({
    error: "Age must be a number"
  }).min(18, {
    error: "You must be 18 or older"
  })
});

Refinement Errors

typescript

const passwordSchema = z.string().refine(
  (password) => /[A-Z]/.test(password),
  { error: "Password must contain at least one uppercase letter" }
).refine(
  (password) => /[0-9]/.test(password),
  { error: "Password must contain at least one number" }
);

Dynamic Error Messages

typescript

const rangeSchema = (min: number, max: number) =>
  z.number().refine(
    (val) => val >= min && val <= max,
    { error: `Value must be between ${min} and ${max}` }
  );

Error Maps

Global Error Map

typescript

import { z } from 'zod';

const customErrorMap: z.ZodErrorMap = (issue, ctx) => {
  if (issue.code === z.ZodIssueCode.invalid_type) {
    if (issue.expected === 'string') {
      return { message: "This field must be text" };
    }
  }

  if (issue.code === z.ZodIssueCode.too_small) {
    if (issue.type === 'string') {
      return { message: `Minimum ${issue.minimum} characters required` };
    }
  }

  return { message: ctx.defaultError };
};

z.setErrorMap(customErrorMap);

Schema-Specific Error Map

typescript

const userSchema = z.object({
  email: z.email(),
  age: z.number()
}, {
  error: (issue, ctx) => {
    if (issue.path[0] === 'email') {
      return { message: "Email address is invalid" };
    }
    return { message: ctx.defaultError };
  }
});

Error Code Reference

typescript

const errorMap: z.ZodErrorMap = (issue, ctx) => {
  switch (issue.code) {
    case z.ZodIssueCode.invalid_type:
      return { message: `Expected ${issue.expected}, got ${issue.received}` };

    case z.ZodIssueCode.invalid_string:
      return { message: "Invalid format" };

    case z.ZodIssueCode.too_small:
      return { message: `Minimum ${issue.minimum} required` };

    case z.ZodIssueCode.too_big:
      return { message: `Maximum ${issue.maximum} allowed` };

    case z.ZodIssueCode.invalid_enum_value:
      return { message: `Must be one of: ${issue.options.join(', ')}` };

    case z.ZodIssueCode.custom:
      return { message: issue.message ?? "Invalid value" };

    default:
      return { message: ctx.defaultError };
  }
};

Error Precedence

Zod v4 error precedence order (highest to lowest):

Schema-level error parameter
Parse-level error map
Global error map (via z.setErrorMap())
Locale error map
Default Zod errors

typescript

z.setErrorMap(globalMap);

const schema = z.string({ error: schemaLevelMap });

const result = schema.safeParse(data, { errorMap: parseLevelMap });

Pretty Print Errors

Console Output

typescript

import { z } from 'zod';

const result = schema.safeParse(data);

if (!result.success) {
  console.error(z.prettifyError(result.error));
}

Format Issues

typescript

const result = schema.safeParse(data);

if (!result.success) {
  result.error.issues.forEach(issue => {
    console.log(`Field: ${issue.path.join('.')}`);
    console.log(`Error: ${issue.message}`);
    console.log(`Code: ${issue.code}`);
  });
}

Framework Integration

Zod integrates seamlessly with popular frameworks for error handling.

Quick patterns:

React Forms: Use safeParse + flatten().fieldErrors
React Hook Form: Use zodResolver for automatic integration
Next.js Server Actions: Return flattened errors to client
Express API: Return 400 status with error details

For framework-specific examples, see the integrating-zod-frameworks skill from the zod-4 plugin.

Best Practices

1. Always Use SafeParse

typescript

const result = schema.safeParse(data);  // ✅
try { schema.parse(data) }              // ❌

2. Provide User-Friendly Messages

typescript

z.email({ error: "Please enter a valid email address" })  // ✅
z.email()                                                  // ❌ Generic error

3. Flatten for Form Display

typescript

const errors = result.error.flatten().fieldErrors;  // ✅
const errors = result.error.issues;                 // ❌ Complex structure

4. Use Error Maps for Consistency

typescript

z.setErrorMap(customMap);  // ✅ Consistent across app

5. Test Error Paths

typescript

it('shows error for invalid email', () => {
  const result = schema.safeParse({ email: 'invalid' });
  expect(result.success).toBe(false);
  if (!result.success) {
    expect(result.error.issues[0].message).toBe("Invalid email");
  }
});

Migration from v3

Error Parameters

Before:

typescript

z.string({ message: "Required" });
z.string({ invalid_type_error: "Must be string" });
z.string({ required_error: "Required" });

After:

typescript

z.string({ error: "Required" });
z.string({ error: "Must be string" });
z.string({ error: "Required" });

Error Maps

Before:

typescript

z.object({}, { errorMap: customMap });

After:

typescript

z.object({}, { error: customMap });

Common Patterns

Nested Object Errors

typescript

const addressSchema = z.object({
  street: z.string({ error: "Street required" }),
  city: z.string({ error: "City required" }),
  zip: z.string({ error: "ZIP code required" })
});

const userSchema = z.object({
  name: z.string(),
  address: addressSchema
});

const result = userSchema.safeParse(data);
if (!result.success) {
  const errors = result.error.flatten();
}

Array Errors

typescript

const schema = z.array(
  z.object({
    name: z.string({ error: "Name required" })
  })
);

const result = schema.safeParse(data);
if (!result.success) {
  result.error.issues.forEach(issue => {
    console.log(`Index ${issue.path[0]}: ${issue.message}`);
  });
}

Union Errors

typescript

const schema = z.union([
  z.string(),
  z.number()
], {
  error: "Must be either string or number"
});

References

Validation: Use the validating-schema-basics skill from the zod-4 plugin
v4 Features: Use the validating-string-formats skill from the zod-4 plugin
Framework integration: Use the integrating-zod-frameworks skill from the zod-4 plugin
Testing: Use the testing-zod-schemas skill from the zod-4 plugin

Cross-Plugin References:

If displaying validation errors in React forms, use the validating-forms skill for error display patterns

Success Criteria

✅ Using unified error parameter
✅ SafeParse pattern for error handling
✅ User-friendly error messages
✅ Flattened errors for form display
✅ Error maps for consistency
✅ Proper error handling in UI frameworks
✅ Test coverage for error paths

Search AI Tools

Install this agent skill to your Project

SKILL.md

Handling Zod Errors

Purpose

Unified Error API

Overview

Error Parameter Types

SafeParse Pattern

Best Practice

Type Inference

Error Formatting

Flatten Errors

Format for Forms

Format for API Responses

Custom Error Messages

Field-Level Errors

Refinement Errors

Dynamic Error Messages

Error Maps

Global Error Map

Schema-Specific Error Map

Error Code Reference

Error Precedence

Pretty Print Errors

Console Output

Format Issues

Framework Integration

Best Practices

1. Always Use SafeParse

2. Provide User-Friendly Messages

3. Flatten for Form Display

4. Use Error Maps for Consistency

5. Test Error Paths

Migration from v3

Error Parameters

Error Maps

Common Patterns

Nested Object Errors

Array Errors

Union Errors

References

Success Criteria