colinhacks/zod · error · Error

BigInt cannot be represented in JSON Schema

Error message

BigInt cannot be represented in JSON Schema

What it means

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.

Solutions

1. Pass { unrepresentable: 'any' } to toJSONSchema() so bigint fields emit an empty schema {} instead of throwing.
2. Replace z.bigint() with z.string().regex(/^-?\d+n?$/) or z.number() in the schema you export, keeping BigInt only for runtime parsing.
3. Map bigint to a documented JSON Schema string pattern via a custom registry/override.

Example fix

// before (throws)
const Schema = z.object({ id: z.bigint() });
z.toJSONSchema(Schema);

// after (opt into the any fallback)
const Schema = z.object({ id: z.bigint() });
z.toJSONSchema(Schema, { unrepresentable: 'any' });
// id becomes {}

// Decide before exporting whether to allow unrepresentable types.
const opts = schemaContains(schema, (s) => s._zod.def.type === 'bigint')
  ? { unrepresentable: 'any' }
  : {};
const json = z.toJSONSchema(schema, opts);

function hasBigInt(schema) {
  // walk the schema tree or inspect _zod.def.type
  return schema._zod.def.type === 'bigint';
}

try {
  return z.toJSONSchema(schema);
} catch (e) {
  if (e.message === 'BigInt cannot be represented in JSON Schema') {
    return z.toJSONSchema(schema, { unrepresentable: 'any' });
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: Models that use BigInt for monetary/ID fields, then needing JSON Schema or OpenAPI output for documentation or code generation.

Related errors

• BigInt literals cannot be represented in JSON Schema
• Custom types cannot be represented in JSON Schema
• Date cannot be represented in JSON Schema
• Dynamic catch values are not supported in JSON Schema
• Function types cannot be represented in JSON Schema

AI-assisted analysis of colinhacks/zod@2d90846af9 (2026-08-11). Data as JSON: /api/errors/03fb0f2fff70381f. Report an issue: GitHub.

Appendix: source

Thrown at packages/zod/src/v4/core/json-schema-processors.ts:104

      json.maximum = exclusiveMaximum;
      json.exclusiveMaximum = true;
    } else {
      json.exclusiveMaximum = exclusiveMaximum;
    }
  } else if (typeof maximum === "number") {
    json.maximum = maximum;
  }

  if (typeof multipleOf === "number") json.multipleOf = multipleOf;
};

export const booleanProcessor: Processor<schemas.$ZodBoolean> = (_schema, _ctx, json, _params) => {
  (json as JSONSchema.BooleanSchema).type = "boolean";
};

export const bigintProcessor: Processor<schemas.$ZodBigInt> = (_schema, ctx, _json, _params) => {
  if (ctx.unrepresentable === "throw") {
    throw new Error("BigInt cannot be represented in JSON Schema");
  }
};

export const symbolProcessor: Processor<schemas.$ZodSymbol> = (_schema, ctx, _json, _params) => {
  if (ctx.unrepresentable === "throw") {
    throw new Error("Symbols cannot be represented in JSON Schema");
  }
};

export const nullProcessor: Processor<schemas.$ZodNull> = (_schema, ctx, json, _params) => {
  if (ctx.target === "openapi-3.0") {
    json.type = "string";
    json.nullable = true;
    json.enum = [null];
  } else {
    json.type = "null";
  }
};

View on GitHub (pinned to 2d90846af9)