{"record":{"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":183,"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":165,"sourceCodeEnd":201,"githubUrl":"https://github.com/colinhacks/zod/blob/2d90846af918af9602e088812d63a035d47cdbe4/packages/zod/src/v4/core/to-json-schema.ts#L165-L201","documentation":"Thrown by the JSON Schema generator when a schema's def.type has no registered processor in ctx.processors. Each Zod type maps to a processor function that emits the corresponding JSON Schema fragment; encountering a type without one (an internal-only type, a custom schema type string, or a type that has no JSON Schema representation) is rejected unless unrepresentable:\"any\" is set, in which case it silently becomes {}.","triggerScenarios":"Calling z.toJSONSchema() on (or embedding within a larger schema) a type that has no JSON Schema processor — typically a custom $ZodType subclass with an unregistered def.type string, or internal types not meant for JSON Schema emission. The error includes the def.type that caused it.","commonSituations":"Authoring a custom schema type without registering a JSON Schema processor; using a zod-mini or experimental schema type whose processor isn't loaded; passing schemas built by a third-party plugin that doesn't ship JSON Schema support; upgrading zod and hitting a renamed internal type string.","solutions":["Pass { unrepresentable: \"any\" } to z.toJSONSchema() to coerce unsupported types to {}.","Register a custom processor for your type via the JSON Schema generator's processor map.","Replace the unsupported type with a JSON-Schema-representable equivalent (e.g. z.string() instead of a custom type).","If the type is internal/accidental, find the schema that produced it and use a supported type instead."],"exampleFix":"// before\nconst json = z.toJSONSchema(MyCustomSchema); // custom type, no processor\n// after\nconst json = z.toJSONSchema(MyCustomSchema, { unrepresentable: \"any\" });","handlingStrategy":"fallback","validationCode":"function toJSONSchemaSafe(schema: z.ZodType) {\n  try {\n    return z.toJSONSchema(schema);\n  } catch (e) {\n    if (/Non-representable type/.test((e as Error).message)) {\n      return z.toJSONSchema(schema, { unrepresentable: \"any\" });\n    }\n    throw e;\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  return z.toJSONSchema(schema);\n} catch (e) {\n  if (/Non-representable type/.test((e as Error).message)) {\n    return z.toJSONSchema(schema, { unrepresentable: \"any\" });\n  }\n  throw e;\n}","preventionTips":["Register a JSON Schema processor for any custom schema type you author.","Default to { unrepresentable: \"any\" } when converting heterogeneous trees.","Map custom types to standard representable types where possible."],"tags":["json-schema","conversion","custom-schema","unrepresentable"],"backgroundTag":null,"analyzedSha":"2d90846af918af9602e088812d63a035d47cdbe4","analyzedAt":"2026-08-11T01:21:44.015Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-22T11:17:16.035Z"}