keyValidator._parse crash: @workflow/world-local mixes zod v3 compat and zod/v4 native schemas

[dlhck]

Bug

@workflow/world-local/dist/queue.js imports zod (v3 compat) and creates a z.object() containing schemas from @workflow/world/dist/queue.js, which imports from zod/v4 (native). When Zod v3's ZodObject._parse() iterates the shape, it calls ._parse() on the v4-native schemas — which don't have that method.

TypeError: keyValidator._parse is not a function

Root cause

@workflow/world/dist/queue.js (line 1):

import { z } from 'zod/v4';  // native v4

Creates ValidQueueName, MessageId etc. as v4-native schemas.

@workflow/world-local/dist/queue.js (line 7):

import z from 'zod';  // v3 compat layer

Then mixes them:

const HeaderParser = z.object({
    'x-vqs-queue-name': ValidQueueName,  // v4 native — no ._parse()
    'x-vqs-message-id': MessageId,        // v4 native — no ._parse()
    'x-vqs-message-attempt': z.coerce.number(), // v3 compat
});

When HeaderParser.safeParse() runs, v3's internal ZodObject._parse() calls shape[key]._parse() on each value. The v4-native schemas don't have ._parse() → crash.

Reproduction

1. Use zod@^3.25 (v4 published under v3 semver, with v3 compat layer)
2. Use workflow@4.2.0-beta.75
3. Trigger any workflow → POST /.well-known/workflow/v1/flow returns 500

Affected versions

• @workflow/world@4.1.0-beta.15
• @workflow/world-local@4.1.0-beta.48
• Also present in older versions (4.0.1-beta.x)

Workaround

Patch @workflow/world-local/dist/queue.js to use import { z } from 'zod/v4' instead of import z from 'zod'.

Suggested fix

Either consistently use zod/v4 in both packages, or consistently use zod (v3 compat). Since @workflow/world/dist/queue.js uses z.templateLiteral() (v4-only API), the fix should be to change @workflow/world-local to also import from zod/v4.

Related

This is the same crash as #686 but with the actual root cause identified. That issue was closed with "upgrade to Zod 4" which only masks the bug.

[dlhck]

Update: The same bug also affects @workflow/world-vercel/dist/queue.js:

import { MessageId, QueuePayloadSchema, ValidQueueName } from '@workflow/world'; // zod/v4 native
import * as z from 'zod'; // v3 compat

const MessageWrapper = z.object({
    queueName: ValidQueueName,  // v4 native → no ._parse()
    // ...
});

This causes workflows on Vercel to start but silently fail on all step executions — VQS retries until timeout, then the workflow gets cancelled. Same root cause, same fix needed.

[VaguelySerious]

(AI) Reproduction

Confirmed. Installing workflow@4.2.0-beta.75 with zod@^3.25 (which resolves to 3.25.76, the v4-under-v3-semver release) and calling safeParse on the HeaderParser in @workflow/world-local/queue.ts crashes with TypeError: keyValidator._parse is not a function. The root cause is exactly as described: @workflow/world/queue.ts imports zod/v4 (native), while @workflow/world-local/queue.ts and @workflow/world-vercel/queue.ts import from zod (v3 compat layer), then embed those v4-native schemas in v3-compat z.object() calls. v4-native schemas lack the internal ._parse() method that v3's ZodObject._parse() expects. @workflow/world-postgres has the same pattern in message.ts and queue.ts.

Related issues

• workflow runs crash with TypeError: keyValidator._parse is not a function #686 — same keyValidator._parse crash, closed with "upgrade to Zod 4" workaround. This PR fixes the actual root cause so users with zod@^3.25 are no longer affected.

Fix

PR #1588 changes the zod import in all queue-related files that consume v4-native schemas from @workflow/world to also use import { z } from 'zod/v4':

• packages/world-local/src/queue.ts
• packages/world-vercel/src/queue.ts
• packages/world-postgres/src/message.ts
• packages/world-postgres/src/queue.ts
• packages/world-postgres/src/zod.ts

Includes a regression test.

To see if this fix solves your issue, could you try to install the pre-release in your package.json? Just replace the workflow dep like so:

{
  "dependencies": {
    "workflow": "https://workflow-docs-git-peter-issue-1587.vercel.sh/workflow.tgz",
    "@workflow/ai": "https://workflow-docs-git-peter-issue-1587.vercel.sh/workflow-ai.tgz"
  }
}