{"record":{"id":"7bfcd96076eb6c74","repo":"ComposioHQ/composio","slug":"experimental-subagent-requires-zod-4-with-z-tojs","errorCode":null,"errorMessage":"experimental_subAgent() requires Zod 4 with z.toJSONSchema() when using options.schema.","messagePattern":"experimental_subAgent\\(\\) requires Zod 4 with z\\.toJSONSchema\\(\\) when using options\\.schema\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"ts/packages/cli/src/services/run-helpers-runtime.ts","lineNumber":370,"sourceCode":"  }\n  const requestedTarget = options.target;\n  if (\n    requestedTarget !== undefined &&\n    requestedTarget !== 'claude' &&\n    requestedTarget !== 'codex' &&\n    requestedTarget !== 'user'\n  ) {\n    throw new Error(\n      'experimental_subAgent() target must be \"claude\", \"codex\", or \"user\" when provided.'\n    );\n  }\n  const inputSchema = options.schema ?? options.jsonSchema;\n  let structuredSchema: Record<string, unknown> | undefined;\n  let zodSchema: z.ZodType | undefined;\n  if (inputSchema !== undefined) {\n    if (inputSchema instanceof z.ZodType) {\n      if (typeof z.toJSONSchema !== 'function') {\n        throw new Error(\n          'experimental_subAgent() requires Zod 4 with z.toJSONSchema() when using options.schema.'\n        );\n      }\n      zodSchema = inputSchema;\n      const generatedSchema = z.toJSONSchema(inputSchema);\n      structuredSchema = Schema.decodeUnknownSync(JsonObject)(generatedSchema);\n    } else if (Predicate.isRecord(inputSchema)) {\n      structuredSchema = inputSchema;\n    } else {\n      throw new Error('experimental_subAgent() schema must be a Zod schema or JSON Schema object.');\n    }\n  }\n  return {\n    ...(requestedTarget === undefined ? {} : { target: requestedTarget }),\n    ...(typeof options.model === 'string' ? { model: options.model } : {}),\n    ...(options.schema === undefined ? {} : { schema: options.schema }),\n    ...(options.jsonSchema === undefined ? {} : { jsonSchema: options.jsonSchema }),\n    ...(structuredSchema === undefined ? {} : { structuredSchema }),","sourceCodeStart":352,"sourceCodeEnd":388,"githubUrl":"https://github.com/ComposioHQ/composio/blob/64b1b85502b1beeb2379e6c9e8bf1104504fa637/ts/packages/cli/src/services/run-helpers-runtime.ts#L352-L388","documentation":"When you pass a Zod schema via options.schema, the CLI must convert it to JSON Schema using z.toJSONSchema(), which only exists in Zod 4. If the installed Zod runtime lacks z.toJSONSchema, this error is thrown during option normalization.","triggerScenarios":"Calling experimental_subAgent(prompt, { schema: z.object({...}) }) while the resolved zod package in the CLI runtime is Zod 3 (which has no toJSONSchema).","commonSituations":"A project pinned to zod@^3, or a duplicate zod install where the schema instance comes from Zod 3 while the CLI expects Zod 4; upgrading the CLI but not zod, or vice versa.","solutions":["Upgrade zod to v4 (pnpm add zod@^4) so z.toJSONSchema exists","Alternatively pass options.jsonSchema with a plain JSON Schema object instead of a Zod schema","Check for duplicate zod installs (pnpm why zod) and dedupe so the schema instance and the CLI share Zod 4"],"exampleFix":"// before\nimport { z } from 'zod'; // zod@3\nawait experimental_subAgent('p', { schema: z.object({ n: z.number() }) });\n// after\npnpm add zod@^4\n// or bypass Zod:\nawait experimental_subAgent('p', { jsonSchema: { type: 'object', properties: { n: { type: 'number' } } } });","handlingStrategy":"validation","validationCode":"import { z } from 'zod';\nif (opts.schema instanceof z.ZodType && typeof z.toJSONSchema !== 'function') {\n  throw new Error('Zod 4 required; use options.jsonSchema instead');\n}","typeGuard":"const hasToJsonSchema = (zz: typeof z): zz is typeof z & { toJSONSchema: (s: z.ZodType) => unknown } => typeof zz.toJSONSchema === 'function';","tryCatchPattern":"catch (e) { if (e instanceof Error && e.message.includes('Zod 4')) { /* fall back to jsonSchema option */ } }","preventionTips":["Pin zod@^4 in package.json","Run pnpm why zod to detect duplicates","Prefer plain JSON Schema when the runtime zod version is unknown"],"tags":["zod","schema","version-mismatch","subagent"],"backgroundTag":"dependency-version-mismatch","analyzedSha":"64b1b85502b1beeb2379e6c9e8bf1104504fa637","analyzedAt":"2026-08-28T15:39:33.623Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}