{"id":"6389c1f8de08e884","repo":"colinhacks/zod","slug":"tojsonschema-non-representable-type-encountered","errorCode":null,"errorMessage":"[toJSONSchema]: Non-representable type encountered: ${def.type}","messagePattern":"\\[toJSONSchema\\]: Non-representable type encountered: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/zod/src/v4/core/to-json-schema.ts","lineNumber":182,"sourceCode":"\n  // custom method overrides default behavior\n  const overrideSchema = schema._zod.toJSONSchema?.();\n  if (overrideSchema) {\n    result.schema = overrideSchema as any;\n  } else {\n    const params = {\n      ..._params,\n      schemaPath: [..._params.schemaPath, schema],\n      path: _params.path,\n    };\n\n    if (schema._zod.processJSONSchema) {\n      schema._zod.processJSONSchema(ctx, result.schema, params);\n    } else {\n      const _json = result.schema;\n      const processor = ctx.processors[def.type];\n      if (!processor) {\n        throw new Error(`[toJSONSchema]: Non-representable type encountered: ${def.type}`);\n      }\n      processor(schema, ctx, _json, params);\n    }\n\n    const parent = schema._zod.parent as T;\n\n    if (parent) {\n      // Also set ref if processor didn't (for inheritance)\n      if (!result.ref) result.ref = parent;\n      process(parent, ctx, params);\n      ctx.seen.get(parent)!.isParent = true;\n    }\n  }\n\n  // metadata\n  const meta = ctx.metadataRegistry.get(schema);\n  if (meta) Object.assign(result.schema, meta);\n","sourceCodeStart":164,"sourceCodeEnd":200,"githubUrl":"https://github.com/colinhacks/zod/blob/912f0f51b0ced654d0069741e7160834dca742ee/packages/zod/src/v4/core/to-json-schema.ts#L164-L200","documentation":"Thrown during `z.toJSONSchema(schema)` when the schema's `def.type` has no registered processor in the JSON-Schema converter's `ctx.processors` map. This means Zod encountered a schema type it does not know how to represent as JSON Schema — typically a custom schema type, an internal type without a converter, or a schema produced by a buggy plugin.","triggerScenarios":"Calling `z.toJSONSchema()` on a custom `$ZodType` subclass whose type string isn't in the processor registry; passing a schema built with low-level `core.$ZodType` constructor directly; using an experimental/extension schema type the converter hasn't been taught.","commonSituations":"Authoring custom Zod types via the core constructor; mixing in third-party Zod plugins that add new schema kinds; version mismatches where a newer schema type isn't supported by an older converter.","solutions":["Check the schema's `_zod.def.type` (shown in the message) — if it is a standard type, the converter should support it; verify you are on a current Zod version.","If it is a custom type, register a `toJSONSchema` override on the schema instance (`_zod.toJSONSchema = () => ({...})`) or a `processJSONSchema` hook so the converter knows how to emit it.","Replace the unsupported custom schema with an equivalent built-in (e.g. a branded/transformed standard type) before conversion."],"exampleFix":"// before\nconst custom = /* a core.$ZodType with def.type = 'myCustom' */;\nz.toJSONSchema(custom); // throws\n\n// after — provide an override\ncustom._zod.toJSONSchema = () => ({ type: 'string', format: 'myCustom' });\nz.toJSONSchema(custom);","handlingStrategy":"try-catch","validationCode":"const SUPPORTED = new Set(['string','number','int','boolean','date','literal','enum','array','object','tuple','union','intersection','record','map','set','promise','function','optional','nullable','default','prefault','nan','bigint','uuid','url','templateLiteral','pipe','lazy','custom','any','unknown','never','void','undefined','null','file']);\nfunction isConvertible(s) {\n  const t = s?._zod?.def?.type;\n  return typeof t === 'string' && (SUPPORTED.has(t) || typeof s._zod.toJSONSchema === 'function' || typeof s._zod.processJSONSchema === 'function');\n}","typeGuard":"function hasConverter(s): boolean {\n  return !!s?._zod && (typeof s._zod.toJSONSchema === 'function' || typeof s._zod.processJSONSchema === 'function');\n}","tryCatchPattern":"try {\n  z.toJSONSchema(schema);\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('[toJSONSchema]: Non-representable type')) {\n    // provide a toJSONSchema override on the custom schema or replace with a built-in\n  }\n  throw e;\n}","preventionTips":["Avoid converting custom core-level schema types unless you register a toJSONSchema/processJSONSchema override.","Keep Zod up to date so all built-in types have converters.","Unit-test toJSONSchema on each schema you intend to expose via JSON Schema."],"tags":["json-schema","conversion","custom-schema"],"analyzedSha":"912f0f51b0ced654d0069741e7160834dca742ee","analyzedAt":"2026-08-03T17:41:55.908Z","schemaVersion":2}