{"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/912f0f51b0ced654d0069741e7160834dca742ee/packages/zod/src/v4/core/json-schema-processors.ts#L151-L187","documentation":"Inside `literalProcessor` (json-schema-processors.ts:163), each literal value is inspected. A value of `undefined` is not representable, so when `ctx.unrepresentable === \"throw\"` the processor throws for `z.literal(undefined)`. With `unrepresentable: \"any\"` the undefined entry is silently dropped from the produced enum/const.","triggerScenarios":"`z.toJSONSchema()` over a schema containing `z.literal(undefined)`, or a multi-value `z.literal([x, undefined])`, with default options.","commonSituations":"Building a literal from a config value that happens to be undefined; unions of literals that include undefined to mean 'absent'.","solutions":["Pass `{ unrepresentable: \"any\" }` so the undefined literal is omitted from the output.","Replace `z.literal(undefined)` with `z.undefined().optional()` or model absence via optionality (`.optional()`).","Filter undefined out of the literal array before constructing the schema."],"exampleFix":"// before\nz.toJSONSchema(z.literal(undefined)); // throws\n// after\nz.toJSONSchema(z.literal(undefined), { unrepresentable: \"any\" });\n// or model it as an optional field instead of a literal","handlingStrategy":"fallback","validationCode":"const json = z.toJSONSchema(schema, { unrepresentable: \"any\" }); // undefined literal is dropped","typeGuard":"function hasUndefinedLiteral(s: z.ZodLiteral<any>): boolean {\n  return [...s.values].some((v) => v === undefined);\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":["Filter `undefined` out of literal value arrays before constructing the schema.","Model absence with `.optional()` instead of `z.literal(undefined)`.","Use `{ unrepresentable: \"any\" }` when converting schemas that may include undefined literals."],"tags":["json-schema","literal","undefined","unrepresentable"],"analyzedSha":"912f0f51b0ced654d0069741e7160834dca742ee","analyzedAt":"2026-08-03T17:41:55.908Z","schemaVersion":2}