Troubleshooting

Common issues, solutions, and debugging tips. The first section covers the free generator; everything after it is specific to PZG Pro features.

🧩 Core Generator Issues

Most symptoms below were fixed in a released version — check your installed version first (npm ls prisma-zod-generator) and upgrade before filing a report.

Error: spawn prisma-zod-generator ENOENT

Cause: Prisma resolves a generator by looking for its executable in the project's node_modules/.bin. The error means it was not there, which usually has one of two causes:

• prisma-zod-generator is not installed in the project (or not installed yet — run pnpm install / npm install).
• Prisma itself is being run from an ephemeral context that does not expose the project's node_modules/.bin, for example pnpx prisma generate or npx --yes prisma generate.

Fix: install the generator locally and run Prisma through your package manager so the local node_modules/.bin is on PATH:

npm install --save-dev prisma-zod-generator
npx prisma generate      # or: pnpm prisma generate / yarn prisma generate

Confirm the binary is linked before filing a report:

ls node_modules/.bin | grep prisma-zod-generator

A global install does not help: Prisma looks in the project, not on the global PATH.

TS2835: Relative import paths need explicit file extensions in ECMAScript imports

Cause: moduleResolution: "nodenext" — or Node's native TypeScript type-stripping — requires explicit extensions on relative ESM imports.

Fix: no zod-generator option is needed. Set moduleFormat = "esm" and importFileExtension = "js" (or "ts") on your prisma-client generator block, and every relative import the zod generator emits inherits the extension. See NodeNext / Native TypeScript Imports.

Smart cleanup deleted my Prisma client output

Symptom: pointing the prisma-client generator and the zod generator at the same output directory, then running prisma generate, removed client.ts / models.ts / enums.ts.

Fix: upgrade to 2.1.5+. Smart cleanup now skips Prisma's own client generator files unconditionally (#365). See Shared Output Directories. On older versions, give each generator its own output directory.

@zod annotations rejected or dropped

Symptoms: object-form error messages such as .min(1, { message: "x" }) are filtered out, or a leading base-type token like .string() errors.

Fix: upgrade to 2.1.6+ (#374). Note that any annotation that still fails validation is reported as Some @zod annotations were invalid and filtered out: — see Logging & Debug Output.

Generated schemas crash at import time under Zod v4

Symptom: importing the generated index throws immediately when a getter-based recursive schema is combined with an optional field.

Fix: upgrade to 2.1.6+ (#377).

Decimal schemas fail to bundle for the browser

Symptom: bundling generated schemas into client-side code pulls in a server-only Prisma entry point.

Fix: upgrade to 2.1.6+ — Decimal schemas now import the browser-safe prisma-client entry (#367).

A model whose name ends in Raw generates the wrong operations

Symptom: a model such as AuditRaw is treated as a MongoDB raw operation and its CRUD schemas are missing or malformed.

Fix: upgrade to 2.1.6+ (#382).

noUnusedLocals errors on generated files

Symptom: 'Prisma' is declared but its value is never read in generated schema files.

Fix: upgrade to 2.1.6+ — unused Prisma type imports are no longer emitted (#378).

dateTimeStrategy ignored in variant files

Symptom: the configured DateTime strategy applies to the main schemas but not to split or array-based variant files.

Fix: upgrade to 2.1.6+ (#368).

AggregateArgs type name has the wrong casing

Symptom: TypeScript cannot resolve the aggregate args type for models with lowercase or snake_case names.

Fix: upgrade to 2.1.6+ (#391).

@zod.import modules missing in single-file mode

Symptom: with useMultipleFiles: false, external imports declared via @zod.import([...]) are stripped and the bundled file does not compile.

Fix: upgrade to 2.3.3+ — custom imports are hoisted into the bundle (#335).

Field @default values look wrong in pure models

Symptoms: a BigInt default emitted as a bare number, a DateTime default as a string, a Decimal default unwrapped, or a Bytes default swallowed by the base64 validation chain.

Fix: upgrade to 2.1.5+ for new Prisma.Decimal(...) wrapping (#372), 2.1.6+ for BigInt("...") / new Date("...") constructors and parsed Json defaults (#373), and 2.1.7+ for Bytes defaults appended after the validation chain (#394). See Bytes & JSON Details.

🔑 License Issues

note

License validation is fully offline — an Ed25519 signature check over a self-contained license payload. No network request is made. A successful check is cached at ~/.cache/pzg/license.json for 30 days, on every plan.

Invalid License Key Error

❌ Invalid PZG Pro license key. Please check your license key.

Causes & Solutions:

1. Expired License: Check expiration date with npx prisma-zod-generator license-check
2. Wrong Environment Variable: Ensure PZG_LICENSE_KEY is set correctly
3. Corrupted Key: Re-copy your license key from the purchase email
4. Public Key Mismatch: Verification uses PZG_LICENSE_PUBLIC_KEY when it is set, otherwise a built-in default key. If you were issued a non-default key and the variable is unset or malformed, the signature check fails and the license reads as invalid.

Debugging Steps:

# Check if license key is set
echo $PZG_LICENSE_KEY

# Validate license
npx prisma-zod-generator license-check

# Test with verbose output
DEBUG_PRISMA_ZOD=1 npx prisma-zod-generator license-check

"PZG Pro modules are not available in this repository"

PZG Pro modules are not available in this repository.
To enable Pro features:
  1. Purchase a PZG Pro license
  2. Initialize the private submodule:
       git submodule update --init --recursive

On 2.3.7 and earlier this message is misleading. The Pro generator answered every license failure with it, including the common case where Pro is installed correctly from npm and the only problem is that PZG_LICENSE_KEY is unset or expired. The git submodule step cannot help an npm consumer, and the real remedy went unmentioned.

If you installed from npm, ignore the submodule advice and check your license instead:

echo $PZG_LICENSE_KEY                        # is it set in *this* shell?
npx prisma-zod-generator license-check       # does it validate?

Environment variables set in your shell profile are not visible to editors or CI runners started before the change — Prisma reads the environment of the process that spawns it, so also confirm the key is present in .env or your CI secrets.

From 2.3.8+ the two cases are reported separately: a missing install still points at the submodule, while a licensing failure names the actual cause (unset key, expired subscription, or tampering) and points at PZG_LICENSE_KEY and license-check.

Code Tampering Warning

❌ PZG Pro code tampering detected. Pro features have been modified.

Why it happens: Integrity checks detected edits to the obfuscated Pro bundle (or the src/pro submodule).

Fix: Reinstall the published package (pnpm install prisma-zod-generator@latest) or reset the src/pro submodule to its shipped commit. Extend functionality via documented APIs instead of modifying bundled code.

🛡️ Policies & Redaction

Policy Comments Not Recognized

Symptom: Policy annotations in schema comments are ignored

Common Causes:

1. Wrong Comment Format: Must use /// @policy or /// @pii
2. Inline Comments: Use separate comment lines, not inline with field
3. Syntax Errors: Check policy expression syntax

Examples:

// ❌ Wrong: inline comment
model User {
  email String /// @pii email redact:logs  // This won't work
}

// ✅ Correct: separate line
model User {
  /// @pii email redact:logs
  email String
}

// ✅ Also correct: above field
model User {
  /// @policy read:role in ["admin"]
  /// @pii email mask:partial
  email String
}

Policy Validation Errors

Symptom: Runtime errors when policies are applied

Debugging:

# Generate with debug output
DEBUG_PRISMA_ZOD=1 pnpm exec prisma generate

# Check generated policy files
ls prisma/generated/pro/policies/
cat prisma/generated/pro/policies/user.ts

PII Redaction Not Working

Check Configuration: Add these keys to the policies JSON config (either inline in schema.prisma or the file referenced via configPath):

{
  "enableRedaction": true,
  "piiFields": ["email", "phone", "ssn"]
}

⚡ Server Actions

Server Action Import Errors

Symptom: Cannot resolve imports in generated actions

Common Issues:

1. Wrong Output Path: Check serverActions.outputPath in config
2. Missing Dependencies: Install required packages
3. TypeScript Errors: Run type check

Solutions:

# Install missing dependencies
npm install @tanstack/react-query next zod

# Check TypeScript errors
npx tsc --noEmit

# Regenerate after updating generator config
# serverActions = "{ \"outputPath\": \"./src/server\" }"
pnpm exec prisma generate

React Hook Errors

Symptom: Hooks not working in components

Requirements:

// ❌ Missing providers
function App() {
  return <CreateUserForm />;  // Hook will fail
}

// ✅ With providers
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <CreateUserForm />
    </QueryClientProvider>
  );
}

"use server" Directive Missing

Solution: Regenerate server actions with latest version

rm -rf prisma/generated/pro/server-actions
pnpm exec prisma generate

📦 SDK Publisher

Where the SDK actually lands

The pack emits two standalone source files, one per requested platform — no package scaffold, no package.json, nothing to build or publish:

ls prisma/generated/pro/sdk/typescript/index.ts
ls prisma/generated/pro/sdk/python/api_client.py

Consume it by importing the file directly, or copy it into a package of your own.

Cannot find name 'Decimal' | 'JsonValue' | 'Buffer'

Symptom: tsc reports TS2304/TS2591 on the generated index.ts.

Cause: versions before 2.4.1 emitted Prisma's own type names into a client that has no Prisma dependency.

Fix: upgrade to 2.4.1+, where those columns are typed as the wire carries them (string | number for Decimal, unknown for Json, string for Bytes and DateTime). On an older version, add a prelude above the interfaces:

import type { Decimal } from '@prisma/client/runtime/library';
type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };

Enum comparisons never match

Symptom: if (member.role === Role.ADMIN) is always false against a JSON response.

Cause: before 2.4.1 enums were emitted without values, making them numeric, so Role.ADMIN was a number while the payload carried the string "ADMIN".

Fix: upgrade to 2.4.1+ for string-valued enums, or compare against the string (member.role === 'ADMIN').

🚨 Drift Guard

CI Integration Issues

Symptom: Drift Guard workflow fails in GitHub Actions

Common Issues:

1. Missing License: Add PZG_LICENSE_KEY to GitHub Secrets
2. Git Depth: Need full git history for comparison
3. Missing Dependencies: Install PZG Pro in CI

Working Workflow:

- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # Important: full history

- name: Install dependencies
  run: npm ci

- name: Run Drift Guard
  env:
    PZG_LICENSE_KEY: ${{ secrets.PZG_LICENSE_KEY }}
  run: npx pzg-pro guard --schema=./prisma/schema.prisma --base origin/main --head HEAD --format github

False Positive Breaking Changes

Symptom: Safe changes reported as breaking

Solutions:

1. Whitelist the change: pass the identifier from the report — repeatable:

   npx pzg-pro guard --allowed-break User.email:field_removed --allowed-break Post.slug:field_removed

   Identifiers are <Model>.<field>:<change> for field-level changes and <Model>:<change> otherwise.
2. Inspect the raw diff: npx pzg-pro guard --format json and check each change's type (breaking / non-breaking), category, and severity.
3. Adjust gating: --strict is what makes the command fail on remaining breaking changes; without it the report is printed and the command exits 0.

Drift Guard has no field-exclusion or threshold configuration — --allowed-break is the supported override. See Pro CLI & API.

🏗️ General Issues

Drift Guard Fails to Read Base Schema

Symptom: fatal: path 'prisma/schema.prisma' does not exist in 'origin/main'

• Ensure the workflow fetches full history (fetch-depth: 0).
• Confirm the --base ref contains the schema file.
• If the file moved, point Drift Guard at the new path via --schema.

Out of Memory Errors

Symptom: Node.js heap out of memory during generation

Solutions:

# Increase memory limit
NODE_OPTIONS="--max-old-space-size=4096" pnpm exec prisma generate

Slow Generation Performance

Optimization Tips:

1. Limit Enabled Packs: Disable enable* flags you don't need for the current run.
2. Filter Models: Disable the models you don't need in your JSON config. Models are enabled by default, so listing some does not exclude the rest:

   { "models": { "AuditLog": { "enabled": false } } }

3. Warm Node Modules: Run pnpm exec prisma generate after dependencies are installed to avoid repeated cold starts.

See Performance & Build Tips for the full list.

TypeScript Compilation Errors

Common Issues:

1. Missing Types: Install @types/* packages
2. Version Conflicts: Check TypeScript version compatibility
3. Module Resolution: Configure tsconfig.json

Recommended tsconfig.json settings (bundler-style resolution):

{
  "compilerOptions": {
    "strict": true,
    "moduleResolution": "bundler",
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": [
    "generated/**/*",
    "src/**/*"
  ]
}

nodenext and Node's native TypeScript support are equally supported — see TS2835 above.

🐛 Debug Mode

Enable Verbose Logging

# Verbose generator logging
DEBUG_PRISMA_ZOD=1 pnpm exec prisma generate

# Equivalent
DEBUG=prisma-zod pnpm exec prisma generate

# Capture to a file
DEBUG_PRISMA_ZOD=1 pnpm exec prisma generate 2> debug.log

# License validation
DEBUG_PRISMA_ZOD=1 npx prisma-zod-generator license-check

note

There are no module-scoped debug namespaces — DEBUG_PRISMA_ZOD=1 enables all generator debug output, and any other DEBUG value leaves it off. See Logging & Debug Output.

📞 Getting Help

Before Reaching Out

1. Check License Status: npx prisma-zod-generator license-check
2. Update to Latest: npm install -D prisma-zod-generator@latest
3. Clear License Cache: rm -rf ~/.cache/pzg (the cache is ~/.cache/pzg/license.json, valid for 30 days)
4. Review Logs: Enable debug mode and check output

Support Channels

• GitHub Issues: Bug reports and feature requests
• Direct Support: DM @omardulaimidev on X (Professional+ customers)

Issue Template

When reporting issues, include:

**PZG Version**: (output of `npm ls prisma-zod-generator`, e.g. 2.3.3)
**Prisma Version**: (e.g. 7.x)
**Zod Version**: (e.g. 4.x)
**Node Version**: (e.g. 20.19.0)
**License Plan**: Pro
**Feature**: Policies & Redaction

**Issue Description**:
[Describe the problem]

**Steps to Reproduce**:
1. Set up schema with...
2. Run command...
3. See error...

**Expected Behavior**:
[What should happen]

**Actual Behavior**:
[What actually happens]

**Debug Output**:
```
DEBUG_PRISMA_ZOD=1 pnpm exec prisma generate
[paste output]
```

**Configuration**:
```
[paste generator pzgPro block or the JSON referenced by configPath]
```

---

Need immediate help? Reach out via the direct support channel above for Professional+ customers.