{"id":"f7f46596d5985a28","repo":"colinhacks/zod","slug":"custom-types-cannot-be-represented-in-json-schema","errorCode":null,"errorMessage":"Custom types cannot be represented in JSON Schema","messagePattern":"Custom types 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":246,"sourceCode":"    if (mime.length === 1) {\n      file.contentMediaType = mime[0]!;\n      Object.assign(_json, file);\n    } else {\n      Object.assign(_json, file); // shared props at root\n      _json.anyOf = mime.map((m) => ({ contentMediaType: m })); // only contentMediaType differs\n    }\n  } else {\n    Object.assign(_json, file);\n  }\n};\n\nexport const successProcessor: Processor<schemas.$ZodSuccess> = (_schema, _ctx, json, _params) => {\n  (json as JSONSchema.BooleanSchema).type = \"boolean\";\n};\n\nexport const customProcessor: Processor<schemas.$ZodCustom> = (_schema, ctx, _json, _params) => {\n  if (ctx.unrepresentable === \"throw\") {\n    throw new Error(\"Custom types cannot be represented in JSON Schema\");\n  }\n};\n\nexport const functionProcessor: Processor<schemas.$ZodFunction> = (_schema, ctx, _json, _params) => {\n  if (ctx.unrepresentable === \"throw\") {\n    throw new Error(\"Function types cannot be represented in JSON Schema\");\n  }\n};\n\nexport const transformProcessor: Processor<schemas.$ZodTransform> = (_schema, ctx, _json, _params) => {\n  if (ctx.unrepresentable === \"throw\") {\n    throw new Error(\"Transforms cannot be represented in JSON Schema\");\n  }\n};\n\nexport const mapProcessor: Processor<schemas.$ZodMap> = (_schema, ctx, _json, _params) => {\n  if (ctx.unrepresentable === \"throw\") {\n    throw new Error(\"Map cannot be represented in JSON Schema\");","sourceCodeStart":228,"sourceCodeEnd":264,"githubUrl":"https://github.com/colinhacks/zod/blob/912f0f51b0ced654d0069741e7160834dca742ee/packages/zod/src/v4/core/json-schema-processors.ts#L228-L264","documentation":"`z.custom()` validates via an opaque user-supplied function whose contract cannot be introspected, so `customProcessor` (json-schema-processors.ts:244) cannot emit a meaningful JSON Schema and throws when `ctx.unrepresentable === \"throw\"` (default).","triggerScenarios":"`z.toJSONSchema()` over a schema containing `z.custom<T>((x) => ...)`, with default options. Common when reusing a hand-written guard inside an otherwise-declarative schema.","commonSituations":"Mixing declarative Zod schemas with bespoke runtime checks (e.g. `z.custom(isEmailAddress)`) and then generating docs/OpenAPI.","solutions":["Pass `{ unrepresentable: \"any\" }` so the custom node becomes an unconstrained schema.","Replace `z.custom(fn)` with a concrete schema (e.g. `z.email()`, `z.string().regex(...)`) that JSON Schema can express.","Use `z.toJSONSchema(schema, { override: (s) => ... })` to hand-author the fragment for the custom node."],"exampleFix":"// before\nz.toJSONSchema(z.object({ x: z.custom((v) => typeof v === \"string\") })); // throws\n// after\nz.toJSONSchema(z.object({ x: z.string() }));","handlingStrategy":"fallback","validationCode":"// Replace opaque custom checks with declarative schemas for contracts.\nconst contractSchema = z.object({ email: z.email() });\nconst json = z.toJSONSchema(contractSchema);\n// Or: z.toJSONSchema(schema, { unrepresentable: \"any\" });","typeGuard":"function usesCustom(schema: z.ZodType): boolean {\n  return schema._zod.traits.has(\"$ZodCustom\");\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":["Avoid `z.custom()` in schemas used for contracts; prefer built-in or regex-based schemas.","Use the `override` callback of `z.toJSONSchema` to hand-author fragments for unavoidable custom nodes.","Keep runtime-validation schemas (with custom) separate from contract schemas."],"tags":["json-schema","custom","unrepresentable","openapi"],"analyzedSha":"912f0f51b0ced654d0069741e7160834dca742ee","analyzedAt":"2026-08-03T17:41:55.908Z","schemaVersion":2}