colinhacks/zod · error · Error

[toJSONSchema]: Non-representable type encountered: ${def.ty

Error message

[toJSONSchema]: Non-representable type encountered: ${def.type}

What it means

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.

Source

Thrown at packages/zod/src/v4/core/to-json-schema.ts:182

  // custom method overrides default behavior
  const overrideSchema = schema._zod.toJSONSchema?.();
  if (overrideSchema) {
    result.schema = overrideSchema as any;
  } else {
    const params = {
      ..._params,
      schemaPath: [..._params.schemaPath, schema],
      path: _params.path,
    };

    if (schema._zod.processJSONSchema) {
      schema._zod.processJSONSchema(ctx, result.schema, params);
    } else {
      const _json = result.schema;
      const processor = ctx.processors[def.type];
      if (!processor) {
        throw new Error(`[toJSONSchema]: Non-representable type encountered: ${def.type}`);
      }
      processor(schema, ctx, _json, params);
    }

    const parent = schema._zod.parent as T;

    if (parent) {
      // Also set ref if processor didn't (for inheritance)
      if (!result.ref) result.ref = parent;
      process(parent, ctx, params);
      ctx.seen.get(parent)!.isParent = true;
    }
  }

  // metadata
  const meta = ctx.metadataRegistry.get(schema);
  if (meta) Object.assign(result.schema, meta);

View on GitHub (pinned to 912f0f51b0)

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.

Example fix

// before
const custom = /* a core.$ZodType with def.type = 'myCustom' */;
z.toJSONSchema(custom); // throws

// after — provide an override
custom._zod.toJSONSchema = () => ({ type: 'string', format: 'myCustom' });
z.toJSONSchema(custom);

Defensive patterns

Strategy: try-catch

Validate before calling

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']);
function isConvertible(s) {
  const t = s?._zod?.def?.type;
  return typeof t === 'string' && (SUPPORTED.has(t) || typeof s._zod.toJSONSchema === 'function' || typeof s._zod.processJSONSchema === 'function');
}

Type guard

function hasConverter(s): boolean {
  return !!s?._zod && (typeof s._zod.toJSONSchema === 'function' || typeof s._zod.processJSONSchema === 'function');
}

Try / catch

try {
  z.toJSONSchema(schema);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('[toJSONSchema]: Non-representable type')) {
    // provide a toJSONSchema override on the custom schema or replace with a built-in
  }
  throw e;
}

Prevention

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.

When it happens

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

Common situations: 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.

Related errors

AI-assisted analysis of colinhacks/zod@912f0f51b0 (2026-08-03). Data as JSON: /data/errors/6389c1f8de08e884.json. Report an issue: GitHub.