{"record":{"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/2d90846af918af9602e088812d63a035d47cdbe4/packages/zod/src/v4/core/json-schema-processors.ts#L86-L122","documentation":"Thrown by toJSONSchema() when a ZodBigInt schema (z.bigint()) is encountered and the converter's unrepresentable mode is 'throw' (the default). JSON Schema has no bigint type — bigints are a JavaScript-specific runtime concept — so the converter refuses to emit a misleading schema unless you opt in to the 'any' fallback.","triggerScenarios":"Calling z.toJSONSchema(z.bigint()) or including a z.bigint() field inside a larger schema passed to toJSONSchema() without setting unrepresentable: 'any'. Generating OpenAPI from an API whose model uses z.bigint() for large IDs.","commonSituations":"Models that use BigInt for monetary/ID fields, then needing JSON Schema or OpenAPI output for documentation or code generation.","solutions":["Pass { unrepresentable: 'any' } to toJSONSchema() so bigint fields emit an empty schema {} instead of throwing.","Replace z.bigint() with z.string().regex(/^-?\\d+n?$/) or z.number() in the schema you export, keeping BigInt only for runtime parsing.","Map bigint to a documented JSON Schema string pattern via a custom registry/override."],"exampleFix":"// before (throws)\nconst Schema = z.object({ id: z.bigint() });\nz.toJSONSchema(Schema);\n\n// after (opt into the any fallback)\nconst Schema = z.object({ id: z.bigint() });\nz.toJSONSchema(Schema, { unrepresentable: 'any' });\n// id becomes {}","handlingStrategy":"try-catch","validationCode":"// Decide before exporting whether to allow unrepresentable types.\nconst opts = schemaContains(schema, (s) => s._zod.def.type === 'bigint')\n  ? { unrepresentable: 'any' }\n  : {};\nconst json = z.toJSONSchema(schema, opts);","typeGuard":"function hasBigInt(schema) {\n  // walk the schema tree or inspect _zod.def.type\n  return schema._zod.def.type === 'bigint';\n}","tryCatchPattern":"try {\n  return z.toJSONSchema(schema);\n} catch (e) {\n  if (e.message === 'BigInt cannot be represented in JSON Schema') {\n    return z.toJSONSchema(schema, { unrepresentable: 'any' });\n  }\n  throw e;\n}","preventionTips":["Default to { unrepresentable: 'any' } when exporting schemas that may contain JS-only types.","Keep BigInt fields out of schemas you export; use a parallel string/number schema for the external contract.","Document which models are safe for JSON Schema export vs runtime-only."],"tags":["json-schema","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"}