colinhacks/zod · error · Error

[toJSONSchema]: Non-representable type encountered

Error message

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

What it means

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 {}.

Solutions

1. Pass { unrepresentable: "any" } to z.toJSONSchema() to coerce unsupported types to {}.
2. Register a custom processor for your type via the JSON Schema generator's processor map.
3. Replace the unsupported type with a JSON-Schema-representable equivalent (e.g. z.string() instead of a custom type).
4. If the type is internal/accidental, find the schema that produced it and use a supported type instead.

Example fix

// before
const json = z.toJSONSchema(MyCustomSchema); // custom type, no processor
// after
const json = z.toJSONSchema(MyCustomSchema, { unrepresentable: "any" });

function toJSONSchemaSafe(schema: z.ZodType) {
  try {
    return z.toJSONSchema(schema);
  } catch (e) {
    if (/Non-representable type/.test((e as Error).message)) {
      return z.toJSONSchema(schema, { unrepresentable: "any" });
    }
    throw e;
  }
}

try {
  return z.toJSONSchema(schema);
} catch (e) {
  if (/Non-representable type/.test((e as Error).message)) {
    return z.toJSONSchema(schema, { unrepresentable: "any" });
  }
  throw e;
}

When it happens

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

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

Related errors

• BigInt cannot be represented in JSON Schema
• BigInt literals cannot be represented in JSON Schema
• Circular reference not resolved
• Conditional schemas (if/then/else) are not supported
• Custom types cannot be represented in JSON Schema

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

Appendix: source

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

  // 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 2d90846af9)