{"record":{"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/2d90846af918af9602e088812d63a035d47cdbe4/packages/zod/src/v4/core/json-schema-processors.ts#L157-L193","documentation":"Thrown by the literalProcessor when a ZodLiteral's accepted values include a bigint (e.g. z.literal(1n)) and unrepresentable is 'throw' (default). BigInt is not a JSON type, so it cannot appear in a JSON Schema const/enum.","triggerScenarios":"Calling toJSONSchema() on z.literal(1n) or z.literal([1n, 2n]). A model whose discriminating literal is a bigint.","commonSituations":"Domain models that use bigint literals for opaque IDs/codes, then feeding the same schema to a JSON Schema or OpenAPI generator.","solutions":["Pass { unrepresentable: 'any' } to toJSONSchema(); the bigint entry is dropped from the literal's values.","For the external contract, model the value as a string or number literal (z.literal('1') or z.literal(1)) and convert at the boundary.","Split runtime and export schemas so bigint literals never reach toJSONSchema()."],"exampleFix":"// before (throws)\nconst Schema = z.literal(1n);\nz.toJSONSchema(Schema);\n\n// after\nconst Schema = z.literal(1n);\nz.toJSONSchema(Schema, { unrepresentable: 'any' }); // yields {}\n// or use a numeric literal for the contract\nconst External = z.literal(1);","handlingStrategy":"try-catch","validationCode":"const opts = schemaContains(schema, (s) =>\n  s._zod.def.type === 'literal' && [...s.values].some((v) => typeof v === 'bigint'))\n  ? { unrepresentable: 'any' }\n  : {};\nconst json = z.toJSONSchema(schema, opts);","typeGuard":"function hasBigintLiteral(schema) {\n  if (schema._zod.def.type !== 'literal') return false;\n  const def = schema._zod.def;\n  return Array.isArray(def.values) && def.values.some((v) => typeof v === 'bigint');\n}","tryCatchPattern":"try {\n  return z.toJSONSchema(schema);\n} catch (e) {\n  if (e.message === 'BigInt literals cannot be represented in JSON Schema') {\n    return z.toJSONSchema(schema, { unrepresentable: 'any' });\n  }\n  throw e;\n}","preventionTips":["Use string or number literals in export schemas; convert bigint at the boundary.","Keep bigint-literal schemas runtime-only.","Default to { unrepresentable: 'any' } when exporting models that may include bigint sentinels."],"tags":["json-schema","literal","bigint","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"}