Skip to content

secondsky/claude-skills / plugins/zod/skills/zod

TypeScript-first schema validation and type inference. Use for validating API requests/responses, form data, env vars, configs, defining type-safe schemas with runtime validation, transforming data, generating JSON Schema for OpenAPI/AI, or encountering missing validation errors, type inference issues, validation error handling problems. Zero dependencies, compact core (~5kb gzipped; zod/mini ~1.9kb).

references/troubleshooting.md

View on GitHub
# Zod Troubleshooting Guide

Solutions for common issues, performance optimization, and best practices.

**Last Updated**: 2026-08-20 (verified against zod@4.4.3)

---

## Known Issues & Solutions

### 1. TypeScript Strict Mode Required

**Issue**: Zod requires TypeScript strict mode (`"strict": true`).

**Error Message**:
```
Type 'string | undefined' is not assignable to type 'string'
```

**Solution**: Enable strict mode in `tsconfig.json`:

```json
{
  "compilerOptions": {
    "strict": true,
    // If enabling strict is impossible, manually enable strictNullChecks
    "strictNullChecks": true
  }
}
```

**Why**: Zod's type inference relies on strict null checking to properly distinguish between `string`, `string | undefined`, and `string | null`.

---

### 2. Large Schema Bundle Size

**Issue**: Complex schemas can increase bundle size significantly.

**Solution 1**: Use dynamic imports for large schemas (`z.lazy` is for circular
references, not code splitting — it expects a schema, not a promise):

```typescript
// Lazy load the schema module when needed
async function validateHeavy(data: unknown) {
  const { HeavySchema } = await import('./schemas/heavy');
  return HeavySchema.safeParse(data);
}
```

**Solution 2**: Code splitting by route/page:

```typescript
// Only load schema when route is accessed
const ProfileSchema = lazy(() => import('./schemas/profile'));
```

**Solution 3**: Extract shared schemas:

```typescript
// Reuse common schemas instead of duplicating
const TimestampSchema = z.object({
  createdAt: z.date(),
  updatedAt: z.date(),
});

// Use in multiple places
const PostSchema = z.object({
  /* ... */
}).extend(TimestampSchema.shape);

const CommentSchema = z.object({
  /* ... */
}).extend(TimestampSchema.shape);
```

---

### 3. Async Refinements Performance

**Issue**: Async refinements (e.g., database checks) can be slow and cause performance bottlenecks.

**Solution 1**: Use caching:

```typescript
const usernameCache = new Map();

const UsernameSchema = z.string().refine(
  async (username) => {
    if (usernameCache.has(username)) {
      return usernameCache.get(username);
    }

    const exists = await checkUsernameExists(username);
    usernameCache.set(username, !exists);
    return !exists;
  },
  { message: "Username already taken" }
);
```

**Solution 2**: Debouncing:

```typescript
import { debounce } from 'lodash';

const checkUsername = debounce(async (username) => {
  return await checkUsernameExists(username);
}, 500);

const UsernameSchema = z.string().refine(
  async (username) => {
    const exists = await checkUsername(username);
    return !exists;
  },
  { message: "Username already taken" }
);
```

**Solution 3**: Move expensive checks to background:

```typescript
// Validate format synchronously
const QuickUsernameSchema = z.string().min(3).max(20).regex(/^[a-z0-9_]+$/);

// Validate availability asynchronously after submission
async function validateUsernameAvailability(username: string) {
  const exists = await checkUsernameExists(username);
  if (exists) {
    throw new Error("Username already taken");
  }
}
```

---

### 4. Error Message Localization

**Issue**: Default error messages are English-only.

**Solution**: Use Zod v4's built-in localization or custom error maps:

**Built-in Locales** (40+ languages):

```typescript
import { z } from "zod";

// Global locale
z.config(z.locales.es());  // Spanish
z.config(z.locales.fr());  // French
z.config(z.locales.ja());  // Japanese

// Per-parse locale
const result = schema.parse(data, {
  locale: z.locales.es(),
});
```

**Custom i18n Integration**:

```typescript
import { t } from 'i18next';

z.config({
  customError: (issue) => t(`validation.${issue.code}`, issue),
});
```

**Example i18n File**:

```json
{
  "validation": {
    "too_small": "Minimum length: {{minimum}}",
    "too_big": "Maximum length: {{maximum}}",
    "invalid_type": "Expected {{expected}}",
    "invalid_format": "Invalid {{format}}"
  }
}
```

---

### 5. Circular Dependencies

**Issue**: Self-referential types can cause TypeScript errors.

**Error Message**:
```
'CategorySchema' is referenced directly or indirectly in its own type annotation.
```

**Solution**: Use `z.lazy()`:

```typescript
interface Category {
  name: string;
  subcategories: Category[];
}

const CategorySchema: z.ZodType<Category> = z.lazy(() =>
  z.object({
    name: z.string(),
    subcategories: z.array(CategorySchema),
  })
);
```

**Why it works**: `z.lazy()` defers schema creation until runtime, breaking the circular reference.

---

### 6. Union Type Performance

**Issue**: Large unions can slow down parsing significantly.

**Slow Example**:

```typescript
// ✗ Tries all 10 branches on failure
const SlowUnion = z.union([
  z.object({ type: z.literal("a"), data: z.string() }),
  z.object({ type: z.literal("b"), data: z.number() }),
  z.object({ type: z.literal("c"), data: z.boolean() }),
  // ... 7 more branches
]);
```

**Solution**: Use `z.discriminatedUnion()`:

```typescript
// ✓ Checks discriminator first, then only 1 branch
const FastUnion = z.discriminatedUnion("type", [
  z.object({ type: z.literal("a"), data: z.string() }),
  z.object({ type: z.literal("b"), data: z.number() }),
  z.object({ type: z.literal("c"), data: z.boolean() }),
  // ... 7 more branches
]);
```

**Performance gain**: ~10x faster for large unions (10+ branches).

---

### 7. Default Values Not Applied on Undefined

**Issue**: `.default()` only applies when value is `undefined`, not for `null` or invalid types.

**Example**:

```typescript
const schema = z.string().default("fallback");

schema.parse(undefined); // "fallback" ✓
schema.parse(null);      // ✗ Error: Expected string, received null
schema.parse(123);       // ✗ Error: Expected string, received number
```

**Solution 1**: Use `.nullish().default()` for null handling:

```typescript
const schema = z.string().nullish().default("fallback");

schema.parse(undefined); // "fallback" ✓
schema.parse(null);      // "fallback" ✓
```

**Solution 2**: Use `.catch()` for fallback on any error:

```typescript
const schema = z.string().catch("fallback");

schema.parse(undefined); // "fallback" ✓
schema.parse(null);      // "fallback" ✓
schema.parse(123);       // "fallback" ✓
```

---

### 8. Transform vs Refine Confusion

**Issue**: Using `.refine()` when `.transform()` is needed (or vice versa).

**Refine** (validation only):
```typescript
// ✓ For validation - returns boolean
z.string().refine((val) => val.length >= 8, "Too short");
```

**Transform** (data modification):
```typescript
// ✓ For transformation - returns new value
z.string().transform((val) => val.trim());
```

**Common Mistake**:
```typescript
// ✗ Wrong - refine doesn't modify data
z.string().refine((val) => val.trim());

// ✓ Correct - use transform to modify
z.string().transform((val) => val.trim());
```

**When to use what**:
- **Refine**: Add validation rules (returns `true`/`false`)
- **Transform**: Modify the data (returns new value)
- **Codec**: Bidirectional transformation (encode + decode)

---

## Performance Tips

### 0. Know Zod 4's Performance Profile

Zod 4 uses JIT compilation: initial schema creation is slightly slower, but repeated
parsing is dramatically faster (roughly 7-14x over v3 in the official benchmarks),
with far fewer TypeScript type instantiations (~100x reduction). Consequences:

- **Create schemas once** (module level) and reuse them — the JIT pays off on the second and later parses.
- **Never build schemas inside hot loops or request handlers** — you pay the creation cost every time and lose the JIT benefit.
- **For extreme bundle budgets**, switch to `zod/mini` (~1.9kb gzipped vs ~5kb core) — a functional API where checks attach via `.check(z.minLength(3))`.

```typescript
// Zod Mini for bundle-sensitive targets
import { z } from "zod/mini";
const Name = z.string().check(z.minLength(1), z.maxLength(100));
const User = z.object({ name: Name });
z.safeParse(User, { name: "a" });
```

### 1. Use `.discriminatedUnion()` instead of `.union()`

**Impact**: 5-10x faster for large unions

```typescript
// ✗ Slow
z.union([...]);

// ✓ Fast
z.discriminatedUnion("type", [...]);
```

---

### 2. Lazy Load Large Schemas

**Impact**: Reduces initial bundle size by 50-80%

```typescript
// Dynamic import the schema module on demand
async function validateHeavy(data: unknown) {
  const { HeavySchema } = await import('./schemas/heavy');
  return HeavySchema.safeParse(data);
}
```

---

### 3. Coerce Sparingly

**Impact**: Coercion adds ~20% overhead

```typescript
// ✗ Slower
z.coerce.number()

// ✓ Faster (if input is already number)
z.number()
```

---

### 4. Cache Schema Instances

**Impact**: Prevents recreation overhead

```typescript
// ✗ Recreated on every request
app.post('/users', (req, res) => {
  const schema = z.object({ ... }); // Bad!
});

// ✓ Created once
const UserSchema = z.object({ ... });
app.post('/users', (req, res) => {
  UserSchema.parse(req.body); // Good!
});
```

---

### 5. Use `.safeParse()` over `.parse()`

**Impact**: Avoids expensive try-catch

```typescript
// ✗ Requires try-catch
try {
  schema.parse(data);
} catch (err) {
  // handle error
}

// ✓ No exceptions
const result = schema.safeParse(data);
if (!result.success) {
  // handle error
}
```

---

### 6. Avoid Deep Nesting

**Impact**: Flat schemas parse 2-3x faster

```typescript
// ✗ Deeply nested
const Nested = z.object({
  level1: z.object({
    level2: z.object({
      level3: z.object({
        value: z.string()
      })
    })
  })
});

// ✓ Flattened
const Flat = z.object({
  level1_level2_level3_value: z.string()
});
```

---

## Best Practices

### 1. Define Schemas at Module Level

```typescript
// ✓ Good - defined once
const UserSchema = z.object({
  name: z.string(),
  email: z.email(),
});

export function validateUser(data: unknown) {
  return UserSchema.safeParse(data);
}

// ✗ Bad - recreated every call
export function validateUser(data: unknown) {
  const schema = z.object({
    name: z.string(),
    email: z.email(),
  });
  return schema.safeParse(data);
}
```

---

### 2. Use `.safeParse()` for User Input

```typescript
// ✓ Best for user input
const result = schema.safeParse(userInput);
if (!result.success) {
  return { errors: z.flattenError(result.error) };
}

// ✗ Can crash on invalid input
const data = schema.parse(userInput); // Throws!
```

---

### 3. Leverage Type Inference

```typescript
// ✓ Let Zod generate types
const UserSchema = z.object({
  name: z.string(),
  age: z.number(),
});
type User = z.infer<typeof UserSchema>;

// ✗ Manual types (out of sync risk)
interface User {
  name: string;
  age: number;
}
```

---

### 4. Add Custom Error Messages

```typescript
// ✓ Clear, actionable errors
z.string().min(8, "Password must be at least 8 characters");
z.email({ error: "Please enter a valid email address" });

// ✗ Default errors (less user-friendly)
z.string().min(8);
z.email();
```

---

### 5. Use Discriminated Unions

```typescript
// ✓ Fast + good type inference
z.discriminatedUnion("type", [
  z.object({ type: z.literal("success"), data: z.any() }),
  z.object({ type: z.literal("error"), message: z.string() }),
]);

// ✗ Slow + poor type inference
z.union([
  z.object({ type: z.literal("success"), data: z.any() }),
  z.object({ type: z.literal("error"), message: z.string() }),
]);
```

---

### 6. Validate Early

```typescript
// ✓ Validate at system boundaries
app.post('/api/users', (req, res) => {
  const result = UserSchema.safeParse(req.body);
  if (!result.success) {
    return res.status(400).json({ errors: result.error });
  }
  // Process validated data
});
```

---

### 7. Compose Small Schemas

```typescript
// ✓ Reusable, maintainable
const TimestampSchema = z.object({
  createdAt: z.date(),
  updatedAt: z.date(),
});

const PostSchema = z.object({
  title: z.string(),
  content: z.string(),
}).extend(TimestampSchema.shape);

// ✗ Repetitive, error-prone
const PostSchema = z.object({
  title: z.string(),
  content: z.string(),
  createdAt: z.date(),
  updatedAt: z.date(),
});
```

---

### 8. Document with `.meta()`

```typescript
// ✓ Self-documenting schemas
const EmailSchema = z.email().meta({
  title: "Email Address",
  description: "User's primary email address",
  examples: ["user@example.com"],
});

// ✗ Undocumented schemas
const EmailSchema = z.email();
```

---

### 9. Test Schemas Thoroughly

```typescript
// ✓ Comprehensive schema tests
describe('UserSchema', () => {
  it('accepts valid user', () => {
    const result = UserSchema.safeParse({
      email: 'user@example.com',
      age: 25,
    });
    expect(result.success).toBe(true);
  });

  it('rejects invalid email', () => {
    const result = UserSchema.safeParse({
      email: 'invalid',
      age: 25,
    });
    expect(result.success).toBe(false);
  });

  it('rejects negative age', () => {
    const result = UserSchema.safeParse({
      email: 'user@example.com',
      age: -5,
    });
    expect(result.success).toBe(false);
  });
});
```

---

### 10. Use Codecs for Serialization

```typescript
// ✓ Bidirectional date conversion
const DateCodec = z.codec(
  z.iso.datetime(),
  z.date(),
  {
    decode: (str) => new Date(str),
    encode: (date) => date.toISOString(),
  }
);

// API request: Date → String
const payload = EventSchema.encode(event);
fetch('/api/events', { body: JSON.stringify(payload) });

// API response: String → Date
const event = EventSchema.decode(await response.json());
```

---

**See also:**
- `migration-guide.md` for upgrading from Zod v3
- `error-handling.md` for error message customization
- `advanced-patterns.md` for performance-optimized patterns
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall