/output-error-zod-import

name: output-error-zod-import
description: Fix Zod schema import issues in Output SDK workflows. Use when seeing "incompatible schema" errors, type errors at step boundaries, schema validation failures, or when schemas don't match between steps.
allowed-tools: [Bash, Read]

Fix Zod Import Source Issues

Overview

This skill helps diagnose and fix a common issue where Zod schemas are imported from the wrong source. Output SDK requires schemas to be imported from `@outputai/core`, not directly from `zod`.

When to Use This Skill

You're seeing:

• "incompatible schema" errors
• Type errors at step boundaries
• Schema validation failures when passing data between steps
• Errors mentioning Zod types not matching
• "Expected ZodObject but received..." errors

Root Cause

The issue occurs when you import `z` from `zod` instead of `@outputai/core`. While both provide Zod schemas, they create different schema instances that aren't compatible with each other within the Output SDK context.

**Why this matters**: Output SDK uses a specific version of Zod internally for serialization and validation. When you use a different Zod instance, the schemas are technically different objects even if they define the same shape.

Symptoms

Error Messages

Error: Incompatible schema types
Error: Schema validation failed: expected compatible Zod instance
TypeError: Cannot read property 'parse' of undefined

Code Patterns That Cause This

// WRONG: Importing from 'zod' directly
import { z } from 'zod';

const inputSchema = z.object( {
  name: z.string()
} );

Solution

Step 1: Find All Zod Imports

Search your codebase for incorrect imports:

grep -r "from 'zod'" src/
grep -r 'from "zod"' src/

Step 2: Update Imports

Change all imports from:

// Wrong
import { z } from 'zod';

To:

// Correct
import { z } from '@outputai/core';

Step 3: Verify No Direct Zod Dependencies

Check your imports don't accidentally use zod elsewhere:

grep -r "import.*zod" src/

All matches should show `@outputai/core`, not `zod`.

Complete Example

Before (Wrong)

// src/workflows/my-workflow/steps/process.ts
import { z } from 'zod';  // Wrong!
import { step } from '@outputai/core';

export const processStep = step( {
  name: 'processData',
  inputSchema: z.object( {
    id: z.string()
  } ),
  outputSchema: z.object( {
    result: z.string()
  } ),
  fn: async input => {
    return { result: `Processed ${input.id}` };
  }
} );

After (Correct)

// src/workflows/my-workflow/steps/process.ts
import { z, step } from '@outputai/core';  // Correct!

export const processStep = step( {
  name: 'processData',
  inputSchema: z.object( {
    id: z.string()
  } ),
  outputSchema: z.object( {
    result: z.string()
  } ),
  fn: async input => {
    return { result: `Processed ${input.id}` };
  }
} );

Verification Steps

1. Check for remaining wrong imports

# Should return no results
grep -r "from 'zod'" src/
grep -r 'from "zod"' src/

2. Build the project

npm run output:worker:build

3. Run the workflow

npx output workflow run <workflowName> --input '<input>'

Prevention

ESLint Rule (if using ESLint)

Add a rule to prevent direct zod imports:

// .eslintrc.js
module.exports = {
  rules: {
    'no-restricted-imports': [ 'error', {
      paths: [ {
        name: 'zod',
        message: "Import { z } from '@outputai/core' instead of 'zod'"
      } ]
    } ]
  }
};

IDE Settings

Configure your editor to auto-import from `@outputai/core`:

For VS Code, add to settings.json:

{
  "typescript.preferences.autoImportFileExcludePatterns": ["zod"]
}

Common Gotchas

Mixed Imports in Same File

Even one wrong import can cause issues:

import { z } from '@outputai/core';
import { z as zod } from 'zod';  // This causes problems!

Indirect Dependencies

If a utility file uses the wrong import and is shared:

// utils/schemas.ts
import { z } from 'zod';  // Wrong! This affects all files using these schemas
export const idSchema = z.string().uuid();

Third-Party Libraries

If using external Zod schemas, you may need to recreate them:

// Don't use: externalLibrary.schema
// Instead: recreate the schema with @outputai/core's z

Related Issues

• If schemas are correct but you still see type errors, check `output-error-missing-schemas`
• For validation failures with correct imports, verify schema definitions match actual data