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:

bash

npx prisma generate

ZodError: Validation Failed

Cause: Data doesn't match schema.

Debug:

typescript

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

Output shows exactly which field failed:

json

{
  "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:

typescript

// 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:

prisma

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

Regenerate after changing:

bash

npx prisma generate

Missing Relations in Query

Cause: relationDepth too shallow.

Fix:

prisma

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

Generation Issues

Generator Not Found

Error:

code

Error: Generator "zodipus" not found

Fix: Install the package:

bash

npm install zodipus

Prisma Version Mismatch

Error:

code

Error: Prisma version mismatch

Fix: Zodipus requires Prisma 6.0+:

bash

npm update prisma @prisma/client

Output Directory Issues

Error:

code

Error: Cannot write to output directory

Fix: Ensure directory exists or is creatable:

bash

mkdir -p ./generated

Custom Schema Not Found

Error:

code

Error: Cannot find custom schema: MyCustomSchema

Fix: Define in custom-schemas.ts:

typescript

// 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:

•Check for hidden characters:

typescript

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

•Check types exactly:

typescript

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

•Test fields individually:

typescript

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:

•Prisma returns Date, schema expects string:

prisma

# Change to coerce
dateFormat = "coerce"

•Invalid date string format:

typescript

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

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

•Null/undefined dates:

typescript

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

Enum Validation Failing

Symptom: Invalid enum value error.

Check case sensitivity:

typescript

// 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:

typescript

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

Check data matches schema:

typescript

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:

typescript

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:

typescript

// 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:

typescript

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

Relation Not Included

Cause: Relation not in query configuration.

Fix:

typescript

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

TypeScript Issues

Types Not Updating

Cause: TypeScript cache.

Fix:

bash

# 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:

typescript

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:

typescript

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

tsconfig paths:

json

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

CLI Debugging

Inspect Schema Structure

bash

# 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:

bash

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

Enable Debug Logging

prisma

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

bash

# 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