{"record":{"id":"631f1e922a00d60b","repo":"colinhacks/zod","slug":"literal-undefined-cannot-be-represented-in-json","errorCode":null,"errorMessage":"Literal `undefined` cannot be represented in JSON Schema","messagePattern":"Literal `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":169,"sourceCode":"  }\n};\n\nexport const enumProcessor: Processor<schemas.$ZodEnum> = (schema, _ctx, json, _params) => {\n  const def = schema._zod.def as schemas.$ZodEnumDef;\n  const values = getEnumValues(def.entries);\n  // Number enums can have both string and number values\n  if (values.every((v) => typeof v === \"number\")) json.type = \"number\";\n  if (values.every((v) => typeof v === \"string\")) json.type = \"string\";\n  json.enum = values;\n};\n\nexport const literalProcessor: Processor<schemas.$ZodLiteral> = (schema, ctx, json, _params) => {\n  const def = schema._zod.def as schemas.$ZodLiteralDef<any>;\n  const vals: (string | number | boolean | null)[] = [];\n  for (const val of def.values) {\n    if (val === undefined) {\n      if (ctx.unrepresentable === \"throw\") {\n        throw new Error(\"Literal `undefined` cannot be represented in JSON Schema\");\n      } else {\n        // do not add to vals\n      }\n    } else if (typeof val === \"bigint\") {\n      if (ctx.unrepresentable === \"throw\") {\n        throw new Error(\"BigInt literals cannot be represented in JSON Schema\");\n      } else {\n        vals.push(Number(val));\n      }\n    } else {\n      vals.push(val);\n    }\n  }\n  if (vals.length === 0) {\n    // do nothing (an undefined literal was stripped)\n  } else if (vals.length === 1) {\n    const val = vals[0]!;\n    json.type = val === null ? (\"null\" as const) : (typeof val as any);","sourceCodeStart":151,"sourceCodeEnd":187,"githubUrl":"https://github.com/colinhacks/zod/blob/2d90846af918af9602e088812d63a035d47cdbe4/packages/zod/src/v4/core/json-schema-processors.ts#L151-L187","documentation":"Thrown by the literalProcessor when a ZodLiteral's accepted values include the JavaScript undefined value and unrepresentable is 'throw' (default). JSON Schema const/enum cannot express undefined (it is not JSON), so the converter refuses rather than emit a const: undefined that downstream tools would misread.","triggerScenarios":"Calling toJSONSchema() on z.literal(undefined) or z.literal([undefined, 'x']). A schema that discriminates on 'this literal is undefined' for an external contract.","commonSituations":"Using undefined as a sentinel literal value internally, then exporting the same schema for API documentation or to drive a JSON-Schema validator.","solutions":["Pass { unrepresentable: 'any' } to toJSONSchema(); the undefined entry is dropped silently from the literal's values.","For the exported contract, replace z.literal(undefined) with z.literal(null) or omit the key (z.optional) to express absence portably.","Branch the schema so the export variant contains only JSON-valid literals."],"exampleFix":"// before (throws)\nconst Schema = z.literal(undefined);\nz.toJSONSchema(Schema);\n\n// after\nconst Schema = z.literal(undefined);\nz.toJSONSchema(Schema, { unrepresentable: 'any' }); // yields {}\n// or use null for the external contract\nconst External = z.literal(null);","handlingStrategy":"try-catch","validationCode":"const opts = schemaContains(schema, (s) =>\n  s._zod.def.type === 'literal' && [...s.values].includes(undefined))\n  ? { unrepresentable: 'any' }\n  : {};\nconst json = z.toJSONSchema(schema, opts);","typeGuard":"function hasUndefinedLiteral(schema) {\n  if (schema._zod.def.type !== 'literal') return false;\n  const def = schema._zod.def;\n  return Array.isArray(def.values) && def.values.includes(undefined);\n}","tryCatchPattern":"try {\n  return z.toJSONSchema(schema);\n} catch (e) {\n  if (e.message === 'Literal `undefined` cannot be represented in JSON Schema') {\n    return z.toJSONSchema(schema, { unrepresentable: 'any' });\n  }\n  throw e;\n}","preventionTips":["Avoid undefined as a literal value in schemas you intend to export.","Use z.literal(null) or z.optional() to express absence in external contracts.","Pass { unrepresentable: 'any' } when exporting schemas with sentinel undefined literals."],"tags":["json-schema","literal","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"}