zodipus-troubleshooting

name	zodipus-troubleshooting
description	Debug and fix Zodipus errors. Use when validation fails, generation errors occur, types don't match, Query Engine behaves unexpectedly, or user encounters any zodipus-related error.
license	MIT
metadata	{"author":"zodipus","version":"1.0.0"}

Troubleshooting

Diagnose and fix common Zodipus issues.

When to Apply

• User gets validation errors
• Generation fails or produces wrong output
• Types don't match expected
• Query Engine returns unexpected results
• User mentions "error", "not working", "failed"
• Import/module resolution issues

Quick Diagnosis

"Cannot find module './generated'"

Cause: Generator hasn't run yet.

Fix:

npx prisma generate

ZodError: Validation Failed

Cause: Data doesn't match schema.

Debug:

const result = schema.safeParse(data);
if (!result.success) {
  console.log(JSON.stringify(result.error.format(), null, 2));
}

Output shows exactly which field failed:

{
  "email": {
    "_errors": ["Invalid email"]
  },
  "createdAt": {
    "_errors": ["Expected date, received string"]
  }
}

"Unknown model: X"

Cause: Model not registered in Query Engine.

Fix: Ensure you import from generated-index:

// Wrong
import { UserSchema } from './generated/models';

// Correct
import { models, modelRelations } from './generated/generated-index';

Type Mismatch: Date vs String

Cause: dateFormat configuration mismatch.

Check your config:

generator zodipus {
  dateFormat = "coerce"  # Accepts Date | string | number
  # or
  dateFormat = "string"  # Requires ISO string only
}

Regenerate after changing:

npx prisma generate

Missing Relations in Query

Cause: relationDepth too shallow.

Fix:

generator zodipus {
  relationDepth = "10"  # Increase depth
}

---

Generation Issues

Generator Not Found

Error:

Error: Generator "zodipus" not found

Fix: Install the package:

npm install zodipus

Prisma Version Mismatch

Error:

Error: Prisma version mismatch

Fix: Zodipus requires Prisma 6.0+:

npm update prisma @prisma/client

Output Directory Issues

Error:

Error: Cannot write to output directory

Fix: Ensure directory exists or is creatable:

mkdir -p ./generated

Custom Schema Not Found

Error:

Error: Cannot find custom schema: MyCustomSchema

Fix: Define in custom-schemas.ts:

// generated/custom-schemas.ts
export const MyCustomSchema = z.object({...});

---

Validation Issues

Validation Failing on Valid Data

Symptom: Data looks correct but fails validation.

Debug steps:

1. Check for hidden characters:

console.log(JSON.stringify(data, null, 2));

2. Check types exactly:

console.log(typeof data.createdAt); // string? Date? number?

3. Test fields individually:

const fields = ['id', 'email', 'name', 'createdAt'];
for (const field of fields) {
  const partial = { [field]: data[field] };
  const result = schema.pick({ [field]: true }).safeParse(partial);
  if (!result.success) {
    console.log(`${field} failed:`, result.error.format());
  }
}

Date Validation Failing

Symptom: Invalid date or Expected string errors.

Common causes:

1. Prisma returns Date, schema expects string:

# Change to coerce
dateFormat = "coerce"

2. Invalid date string format:

// Invalid
{ createdAt: "01/15/2024" }

// Valid (ISO 8601)
{ createdAt: "2024-01-15T00:00:00.000Z" }

3. Null/undefined dates:

// Schema requires date, got null
{ createdAt: null } // Error if field not optional

Enum Validation Failing

Symptom: Invalid enum value error.

Check case sensitivity:

// Prisma enum
enum Role {
  USER
  ADMIN
}

// Must match exactly
{ role: 'USER' }  // OK
{ role: 'user' }  // Error
{ role: 'User' }  // Error

JSON Field Validation Failing

Symptom: @zodSchema field failing validation.

Check custom schema exists:

// generated/custom-schemas.ts
export const MySchema = z.object({
  // Not z.unknown() - actual schema
});

Check data matches schema:

import { MySchema } from './generated/custom-schemas';

const result = MySchema.safeParse(data.jsonField);
console.log(result);

---

Query Engine Issues

"Cannot read property 'parse' of undefined"

Cause: Query builder not created properly.

Fix:

const registry = createRegistry({ models, relations: modelRelations });
const userQuery = registry.createQuery('user'); // Returns function
const query = userQuery({ select: { id: true } }); // Call it
query.parse(data); // Now has parse method

Array vs Single Item Mismatch

Error: Expected object, received array

Fix: Use .array() for findMany:

// Wrong
const users = await prisma.user.findMany(query.query);
query.parse(users); // Error: expected object

// Correct
query.array().parse(users);

Missing Fields in Validated Result

Cause: Field not in select.

Fix: Add to selection:

const query = userQuery({
  select: {
    id: true,
    email: true,
    // Add missing field
    name: true,
  }
});

Relation Not Included

Cause: Relation not in query configuration.

Fix:

const query = userQuery({
  select: { id: true },
  // Add relation
  posts: {
    select: { id: true, title: true }
  }
});

---

TypeScript Issues

Types Not Updating

Cause: TypeScript cache.

Fix:

# Restart TS server in VSCode
Cmd+Shift+P → "TypeScript: Restart TS Server"

# Or regenerate
npx prisma generate

"Type 'X' is not assignable to type 'Y'"

Debug: Check inferred type:

import { z } from 'zod';

const query = userQuery({ select: { id: true } });
type QueryResult = z.infer<ReturnType<typeof query.parse>>;
// Hover over QueryResult to see actual type

Import Path Issues

ESM/CJS conflicts:

// Try different import styles
import { UserSchema } from './generated';
import { UserSchema } from './generated/index';
import { UserSchema } from './generated/models';

tsconfig paths:

{
  "compilerOptions": {
    "paths": {
      "@generated/*": ["./generated/*"]
    }
  }
}

---

CLI Debugging

Inspect Schema Structure

# View all models
npx zodipus inspect prisma/schema.prisma --models

# View enums
npx zodipus inspect prisma/schema.prisma --enums

# View relations
npx zodipus inspect prisma/schema.prisma --relations

# Full JSON output
npx zodipus inspect prisma/schema.prisma --json

Dry Run Generation

Preview without writing:

npx zodipus generate prisma/schema.prisma --dry-run

Enable Debug Logging

generator zodipus {
  debug = "true"
}

---

Common Error Messages

Error	Cause	Fix
Cannot find module	Not generated	npx prisma generate
Invalid enum value	Case mismatch	Use exact enum value
Expected string, received object	Date format	Set dateFormat = "coerce"
Unknown model	Wrong import	Import from generated-index
Expected object, received array	Missing .array()	Use query.array().parse()
Property does not exist	Not selected	Add to select
Relation not found	Depth too shallow	Increase relationDepth

---

Getting Help

1. Collect Information

# Prisma version
npx prisma --version

# Node version
node --version

# Package versions
npm list zodipus zod

2. Minimal Reproduction

Create a minimal schema.prisma that reproduces the issue.

3. Check GitHub Issues

Search existing issues: github.com/zodipus/zodipus/issues

4. File a Bug Report

Include:

• Prisma schema (simplified)
• Code causing error
• Full error message
• Package versions