{"id":"03fb0f2fff70381f","repo":"colinhacks/zod","slug":"bigint-cannot-be-represented-in-json-schema","errorCode":null,"errorMessage":"BigInt cannot be represented in JSON Schema","messagePattern":"BigInt 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":104,"sourceCode":"      json.maximum = exclusiveMaximum;\n      json.exclusiveMaximum = true;\n    } else {\n      json.exclusiveMaximum = exclusiveMaximum;\n    }\n  } else if (typeof maximum === \"number\") {\n    json.maximum = maximum;\n  }\n\n  if (typeof multipleOf === \"number\") json.multipleOf = multipleOf;\n};\n\nexport const booleanProcessor: Processor<schemas.$ZodBoolean> = (_schema, _ctx, json, _params) => {\n  (json as JSONSchema.BooleanSchema).type = \"boolean\";\n};\n\nexport const bigintProcessor: Processor<schemas.$ZodBigInt> = (_schema, ctx, _json, _params) => {\n  if (ctx.unrepresentable === \"throw\") {\n    throw new Error(\"BigInt cannot be represented in JSON Schema\");\n  }\n};\n\nexport 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};","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/colinhacks/zod/blob/912f0f51b0ced654d0069741e7160834dca742ee/packages/zod/src/v4/core/json-schema-processors.ts#L86-L122","documentation":"JSON Schema has no representation for arbitrary-precision integers, so `bigintProcessor` (json-schema-processors.ts:102) refuses to convert `z.bigint()`. It throws only when `ctx.unrepresentable === \"throw\"`, which is the default (to-json-schema.ts:128 sets `params?.unrepresentable ?? \"throw\"`). Pass `unrepresentable: \"any\"` to silently emit an empty `any` schema instead.","triggerScenarios":"Calling `z.toJSONSchema(schema)` (or `.toJSONSchema()` via the registry / standard-schema path) on a schema tree that contains `z.bigint()` anywhere, with the default `unrepresentable` setting.","commonSituations":"Generating OpenAPI / JSON Schema docs for an API that uses bigint IDs or timestamps; serializing a shared schema to ship to a frontend; feeding a mixed schema (some bigint columns) into a tool that consumes JSON Schema.","solutions":["Pass `{ unrepresentable: \"any\" }` to `z.toJSONSchema()` so bigint nodes become unconstrained schemas.","Replace `z.bigint()` with `z.string()` or `z.number()` in the schema you convert (coerce at the boundary) if you need a concrete JSON type.","If bigint must round-trip, model it as `z.string().regex(/^\\d+$/)` and document the convention."],"exampleFix":"// before\nz.toJSONSchema(z.object({ id: z.bigint() })); // throws\n// after\nz.toJSONSchema(z.object({ id: z.bigint() }), { unrepresentable: \"any\" });","handlingStrategy":"fallback","validationCode":"// Opt into 'any' for unrepresentable nodes before converting.\nconst json = z.toJSONSchema(schema, { unrepresentable: \"any\" });","typeGuard":"import { z } from \"zod\";\n\nfunction containsBigInt(schema: z.ZodType): boolean {\n  if (z.core.$ZodType && schema._zod.traits.has(\"$ZodBigInt\")) return true;\n  // walk def for nested children recursively as needed\n  return false;\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":["Default to `{ unrepresentable: \"any\" }` when converting schemas that may contain bigint.","Keep a separate 'contract' schema using string/number for IDs/timestamps.","Document which fields are bigint so contract consumers know to expect strings."],"tags":["json-schema","bigint","unrepresentable","openapi"],"analyzedSha":"912f0f51b0ced654d0069741e7160834dca742ee","analyzedAt":"2026-08-03T17:41:55.908Z","schemaVersion":2}