{"id":"75c2c37fd6f5c60f","repo":"colinhacks/zod","slug":"bigint-literals-cannot-be-represented-in-json-sche","errorCode":null,"errorMessage":"BigInt literals cannot be represented in JSON Schema","messagePattern":"BigInt literals 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":175,"sourceCode":"  // 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);\n    if (ctx.target === \"draft-04\" || ctx.target === \"openapi-3.0\") {\n      json.enum = [val];\n    } else {\n      json.const = val;\n    }\n  } else {","sourceCodeStart":157,"sourceCodeEnd":193,"githubUrl":"https://github.com/colinhacks/zod/blob/912f0f51b0ced654d0069741e7160834dca742ee/packages/zod/src/v4/core/json-schema-processors.ts#L157-L193","documentation":"In `literalProcessor` (json-schema-processors.ts:173), a literal value whose `typeof` is `\"bigint\"` cannot be encoded in JSON. With `ctx.unrepresentable === \"throw\"` (default) it throws; with `unrepresentable: \"any\"` it falls back to `vals.push(Number(val))` (coerces to a number, losing precision for large values).","triggerScenarios":"`z.toJSONSchema()` over `z.literal(BigInt(5))` or `z.literal([1n, 2n])`, with default options.","commonSituations":"Using bigint literals for IDs/bitmasks and then generating a contract; converting schemas built from database bigint constants.","solutions":["Pass `{ unrepresentable: \"any\" }` (note: large bigints will be lossy via `Number()`).","Replace the bigint literal with a string literal (`z.literal(\"5\")`) and convert at the boundary to preserve precision.","Use a string regex schema (`z.string().regex(/^\\d+$/)`) instead of a bigint literal for the contract."],"exampleFix":"// before\nz.toJSONSchema(z.literal(BigInt(5))); // throws\n// after\nz.toJSONSchema(z.literal(\"5\")); // -> { type: \"string\", const: \"5\" }","handlingStrategy":"fallback","validationCode":"// For lossless contracts, encode bigints as string literals.\nconst contractSchema = z.literal(\"5\");\nconst json = z.toJSONSchema(contractSchema);\n// Or opt into lossy numeric coercion:\n// z.toJSONSchema(schema, { unrepresentable: \"any\" });","typeGuard":"function hasBigIntLiteral(s: z.ZodLiteral<any>): boolean {\n  return [...s.values].some((v) => typeof v === \"bigint\");\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 string literals over bigint literals in schemas destined for JSON Schema (preserves precision).","Be aware that `unrepresentable: \"any\"` coerces bigints via `Number()`, which is lossy for large values.","Keep bigint literals in runtime-only schemas separate from contract schemas."],"tags":["json-schema","literal","bigint","unrepresentable","precision"],"analyzedSha":"912f0f51b0ced654d0069741e7160834dca742ee","analyzedAt":"2026-08-03T17:41:55.908Z","schemaVersion":2}