{"id":"daeb7c79fde9cf18","repo":"colinhacks/zod","slug":"undefined-cannot-be-represented-in-json-schema","errorCode":null,"errorMessage":"Undefined cannot be represented in JSON Schema","messagePattern":"Undefined cannot be represented in JSON Schema","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/zod/src/v4/core/json-schema-processors.ts","lineNumber":126,"sourceCode":"export const symbolProcessor: Processor<schemas.$ZodSymbol> = (_schema, ctx, _json, _params) => {\n  if (ctx.unrepresentable === \"throw\") {\n    throw new Error(\"Symbols cannot be represented in JSON Schema\");\n  }\n};\n\nexport const nullProcessor: Processor<schemas.$ZodNull> = (_schema, ctx, json, _params) => {\n  if (ctx.target === \"openapi-3.0\") {\n    json.type = \"string\";\n    json.nullable = true;\n    json.enum = [null];\n  } else {\n    json.type = \"null\";\n  }\n};\n\nexport const undefinedProcessor: Processor<schemas.$ZodUndefined> = (_schema, ctx, _json, _params) => {\n  if (ctx.unrepresentable === \"throw\") {\n    throw new Error(\"Undefined cannot be represented in JSON Schema\");\n  }\n};\n\nexport const voidProcessor: Processor<schemas.$ZodVoid> = (_schema, ctx, _json, _params) => {\n  if (ctx.unrepresentable === \"throw\") {\n    throw new Error(\"Void cannot be represented in JSON Schema\");\n  }\n};\n\nexport const neverProcessor: Processor<schemas.$ZodNever> = (_schema, _ctx, json, _params) => {\n  json.not = {};\n};\n\nexport const anyProcessor: Processor<schemas.$ZodAny> = (_schema, _ctx, _json, _params) => {\n  // empty schema accepts anything\n};\n\nexport const unknownProcessor: Processor<schemas.$ZodUnknown> = (_schema, _ctx, _json, _params) => {","sourceCodeStart":108,"sourceCodeEnd":144,"githubUrl":"https://github.com/colinhacks/zod/blob/912f0f51b0ced654d0069741e7160834dca742ee/packages/zod/src/v4/core/json-schema-processors.ts#L108-L144","documentation":"`undefined` is not a JSON value, so `undefinedProcessor` (json-schema-processors.ts:124) will not convert `z.undefined()`. It throws when `ctx.unrepresentable === \"throw\"` (default). Use `unrepresentable: \"any\"` to skip, or model the field as optional/omitted instead.","triggerScenarios":"`z.toJSONSchema()` over a schema containing `z.undefined()` (a field whose only valid value is `undefined`), with default options. Often appears in tuple/union branches or explicit undefined sentinels.","commonSituations":"Generating a contract for a schema that models the absence of a value with `z.undefined()`; converting a discriminated union where one branch is literally undefined.","solutions":["Pass `{ unrepresentable: \"any\" }` to `z.toJSONSchema()`.","Re-model the field as optional (`.optional()`) or omit it from the object shape, since JSON omits absent keys rather than encoding undefined.","Use `z.null()` if the JSON representation should be explicit `null`."],"exampleFix":"// before\nz.toJSONSchema(z.object({ x: z.undefined() })); // throws\n// after\nz.toJSONSchema(z.object({ x: z.undefined().optional() }), { unrepresentable: \"any\" });","handlingStrategy":"fallback","validationCode":"const json = z.toJSONSchema(schema, { unrepresentable: \"any\" });","typeGuard":"function usesUndefined(schema: z.ZodType): boolean {\n  return schema._zod.traits.has(\"$ZodUndefined\");\n}","tryCatchPattern":"try {\n  return z.toJSONSchema(schema);\n} catch (e) {\n  if (e instanceof Error && /cannot be represented in JSON Schema/.test(e.message)) {\n    return z.toJSONSchema(schema, { unrepresentable: \"any\" });\n  }\n  throw e;\n}","preventionTips":["Prefer `.optional()` over `z.undefined()` to model absent fields.","Use `{ unrepresentable: \"any\" }` when converting schemas that include undefined sentinels.","Map absence to `null` in JSON contracts where an explicit value is needed."],"tags":["json-schema","undefined","unrepresentable","openapi"],"analyzedSha":"912f0f51b0ced654d0069741e7160834dca742ee","analyzedAt":"2026-08-03T17:41:55.908Z","schemaVersion":2}