colinhacks/zod · error · Error

not is not supported in Zod

Error message

not is not supported in Zod (except { not: {} } for never)

What it means

Thrown by convertBaseSchema (packages/zod/src/v4/classic/from-json-schema.ts:154) when the source JSON Schema uses the `not` keyword in any form other than the special `{ not: {} }` (which Zod maps to z.never()). Zod has no general negation combinator, so the converter deliberately rejects non-trivial `not` clauses rather than silently dropping the constraint.

Solutions

  1. Remove or rewrite the `not` constraint in the source schema before conversion (Zod cannot express it).
  2. If the intent is 'never', use exactly `{ not: {} }` which converts to z.never().
  3. Approximate the negation with a custom .refine() after conversion: `schema.refine((v) => !predicate(v))`.
  4. Use z.union/z.any with explicit allowed shapes instead of a `not` exclusion.

Example fix

// before
const schema = { not: { type: 'string' } };
fromJSONSchema(schema); // throws: not is not supported

// after — approximate with a post-conversion refinement
const zodSchema = z.any().refine((v) => typeof v !== 'string');
Defensive patterns

Strategy: validation

Validate before calling

function assertNoUnsupportedNot(root: unknown) {
  const visit = (node: unknown): void => {
    if (Array.isArray(node)) return node.forEach(visit);
    if (!node || typeof node !== 'object') return;
    const o = node as Record<string, unknown>;
    if (o.not !== undefined) {
      const isEmpty = typeof o.not === 'object' && o.not !== null && Object.keys(o.not).length === 0;
      if (!isEmpty) throw new Error(`Unsupported non-trivial 'not' found: ${JSON.stringify(o.not)}`);
    }
    for (const v of Object.values(o)) visit(v);
  };
  visit(root);
}

Type guard

null

Try / catch

null

Prevention

When it happens

Trigger: Calling fromJSONSchema on a schema that includes `not` with a non-empty subschema, e.g. `{ not: { type: 'string' } }` or `{ not: { required: ['x'] } }`. Any `not` whose value is an object with at least one keyword triggers the throw.

Common situations: Importing schemas authored for stricter JSON Schema validators that use `not` for negative constraints; OpenAPI specs that use `not` to forbid certain shapes; legacy schemas that express 'anything but X' patterns; auto-generated schemas from TypeScript types that include negation.

Related errors

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

Appendix: source

Thrown at packages/zod/src/v4/classic/from-json-schema.ts:154

  if (path[0] === defsKey) {
    const key = path[1];
    if (!key || !ctx.defs[key]) {
      throw new Error(`Reference not found: ${ref}`);
    }
    return ctx.defs[key]!;
  }

  throw new Error(`Reference not found: ${ref}`);
}

function convertBaseSchema(schema: JSONSchema.JSONSchema, ctx: ConversionContext): ZodType {
  // Handle unsupported features
  if (schema.not !== undefined) {
    // Special case: { not: {} } represents never
    if (typeof schema.not === "object" && Object.keys(schema.not).length === 0) {
      return z.never();
    }
    throw new Error("not is not supported in Zod (except { not: {} } for never)");
  }
  if (schema.unevaluatedItems !== undefined) {
    throw new Error("unevaluatedItems is not supported");
  }
  if (schema.unevaluatedProperties !== undefined) {
    throw new Error("unevaluatedProperties is not supported");
  }
  if (schema.if !== undefined || schema.then !== undefined || schema.else !== undefined) {
    throw new Error("Conditional schemas (if/then/else) are not supported");
  }
  if (schema.dependentSchemas !== undefined || schema.dependentRequired !== undefined) {
    throw new Error("dependentSchemas and dependentRequired are not supported");
  }

  // Handle $ref
  if (schema.$ref) {
    const refPath = schema.$ref;
    if (ctx.refs.has(refPath)) {

View on GitHub (pinned to 2d90846af9)