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.
Fixes Zod schema import issues in Output SDK workflows. Use when seeing "incompatible schema" errors, type errors at step boundaries, or schema validation failures between steps.
/plugin marketplace add growthxai/output-claude-plugins/plugin install growthxai-outputai-plugins-outputai@growthxai/output-claude-pluginsThis skill is limited to using the following tools:
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 @output.ai/core, not directly from zod.
You're seeing:
The issue occurs when you import z from zod instead of @output.ai/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.
Error: Incompatible schema types
Error: Schema validation failed: expected compatible Zod instance
TypeError: Cannot read property 'parse' of undefined
// WRONG: Importing from 'zod' directly
import { z } from 'zod';
const inputSchema = z.object({
name: z.string(),
});
Search your codebase for incorrect imports:
grep -r "from 'zod'" src/
grep -r 'from "zod"' src/
Change all imports from:
// Wrong
import { z } from 'zod';
To:
// Correct
import { z } from '@output.ai/core';
Check your imports don't accidentally use zod elsewhere:
grep -r "import.*zod" src/
All matches should show @output.ai/core, not zod.
// src/workflows/my-workflow/steps/process.ts
import { z } from 'zod'; // Wrong!
import { step } from '@output.ai/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}` };
},
});
// src/workflows/my-workflow/steps/process.ts
import { z, step } from '@output.ai/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}` };
},
});
# Should return no results
grep -r "from 'zod'" src/
grep -r 'from "zod"' src/
npm run output:workflow:build
npx output workflow run <workflowName> '<input>'
Add a rule to prevent direct zod imports:
// .eslintrc.js
module.exports = {
rules: {
'no-restricted-imports': ['error', {
paths: [{
name: 'zod',
message: "Import { z } from '@output.ai/core' instead of 'zod'"
}]
}]
}
};
Configure your editor to auto-import from @output.ai/core:
For VS Code, add to settings.json:
{
"typescript.preferences.autoImportFileExcludePatterns": ["zod"]
}
Even one wrong import can cause issues:
import { z } from '@output.ai/core';
import { z as zod } from 'zod'; // This causes problems!
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();
If using external Zod schemas, you may need to recreate them:
// Don't use: externalLibrary.schema
// Instead: recreate the schema with @output.ai/core's z
output-error-missing-schemasThis skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.