{"record":{"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/2d90846af918af9602e088812d63a035d47cdbe4/packages/zod/src/v4/core/json-schema-processors.ts#L108-L144","documentation":"Thrown by toJSONSchema() when a ZodUndefined schema (z.undefined()) is encountered with unrepresentable set to 'throw' (default). JSON has no representation for the explicit absence that undefined denotes (null is a value; undefined is not), so the converter refuses rather than silently emitting a wrong type.","triggerScenarios":"A schema with an explicitly-typed z.undefined() field passed to toJSONSchema(). Using z.undefined() to model 'property must be absent' and then exporting the schema to JSON Schema.","commonSituations":"Differentiating 'missing key' (undefined) from 'null value' in input, then needing to document that contract in JSON Schema/OpenAPI.","solutions":["Pass { unrepresentable: 'any' } to toJSONSchema() so the undefined field collapses to {}.","Model absence with z.optional(...) / omitting the key instead of an explicit z.undefined() field for the exported contract.","Use z.null() where the external representation should be JSON null."],"exampleFix":"// before (throws)\nconst Schema = z.object({ ghost: z.undefined() });\nz.toJSONSchema(Schema);\n\n// after\nconst Schema = z.object({ ghost: z.undefined() });\nz.toJSONSchema(Schema, { unrepresentable: 'any' });","handlingStrategy":"try-catch","validationCode":"const opts = schemaContains(schema, (s) => s._zod.def.type === 'undefined')\n  ? { unrepresentable: 'any' }\n  : {};\nconst json = z.toJSONSchema(schema, opts);","typeGuard":"function hasUndefined(schema) {\n  return schema._zod.def.type === 'undefined';\n}","tryCatchPattern":"try {\n  return z.toJSONSchema(schema);\n} catch (e) {\n  if (e.message === 'Undefined cannot be represented in JSON Schema') {\n    return z.toJSONSchema(schema, { unrepresentable: 'any' });\n  }\n  throw e;\n}","preventionTips":["Prefer z.optional() or omitted keys over explicit z.undefined() in export schemas.","Use z.null() where the wire representation should be JSON null.","Pass { unrepresentable: 'any' } when exporting mixed schemas."],"tags":["json-schema","undefined","unrepresentable","to-json-schema"],"backgroundTag":null,"analyzedSha":"2d90846af918af9602e088812d63a035d47cdbe4","analyzedAt":"2026-08-11T01:21:44.015Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-22T11:17:16.035Z"}