mastra-ai/mastra · error

Unsupported schema type

Error message

Unsupported schema type: ${typeof schema}

What it means

toStandardSchema() in packages/schema-compat converts any supported schema form (Zod v3/v4, AI SDK Schema, StandardSchemaWithJSON, JSON Schema object) into a Standard Schema. Before treating the input as a plain JSON Schema object it asserts it is a non-null object or function. If the value is null, undefined, a primitive (string/number/boolean), or any other non-object type, it throws this error because there is no conversion path for it.

Solutions

  1. Ensure the schema variable is actually defined and imported before calling the API (check for undefined/missing imports).
  2. Pass the schema object itself, not a schema name, string, or JSON string.
  3. If the schema is loaded asynchronously/lazily, await or resolve it before registering the tool/agent.
  4. Wrap the call in a check: if (schema == null || typeof schema !== 'object') throw a descriptive app-level error before reaching Mastra.

Example fix

// before
new Tool({ parameters: process.env.TOOL_SCHEMA as any }) // undefined or a JSON string
// after
import { z } from 'zod';
new Tool({ parameters: z.object({ query: z.string() }) })
Defensive patterns

Strategy: type-guard

Validate before calling

function assertValidSchemaInput(s: unknown): void {
  if (s === null || (typeof s !== 'object' && typeof s !== 'function')) {
    throw new TypeError(`Expected a schema object, got: ${s === null ? 'null' : typeof s}`);
  }
}

Type guard

const isSchemaObject = (s: unknown): s is Record<string, unknown> =>
  typeof s === 'object' && s !== null;

Try / catch

try {
  return toStandardSchema(schema);
} catch (e) {
  if (e.message.startsWith('Unsupported schema type')) {
    throw new Error(`Schema must be a Zod/JSON Schema/StandardSchema object, got ${typeof schema}`);
  }
  throw e;
}

Prevention

When it happens

Trigger: Calling toStandardSchema (directly or via wrapped/result/rewrapped) with null, undefined, a string like 'zod-schema', a number, or a boolean instead of an actual schema object.

Common situations: Schema loaded from a lazily-initialized config that is still undefined at call time; a typo'd import yielding undefined; passing the *name* of a schema instead of the schema object; JSON.parse failure upstream returning a primitive; destructuring a tool/agent definition where the schema field is missing.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/a50fb6d7f9f599c9. Report an issue: GitHub.

Appendix: source

Thrown at packages/schema-compat/src/standard-schema/standard-schema.ts:174

    });
  }

  // Check for Zod v3 schemas (need wrapping to add JSON Schema support)
  // Important: Must use isZodV3() not instanceof z3.ZodType because
  // Zod v4 schemas are also instanceof z3.ZodType due to prototype compatibility
  if (isZodV3(schema)) {
    return toStandardSchemaZodV3(schema as ZodType);
  }

  // Check for AI SDK Schema objects (Vercel's jsonSchema wrapper)
  if (isVercelSchema(schema)) {
    return toStandardSchemaAiSdk(schema as Schema<T>);
  }

  // At this point, assume it's a plain JSON Schema object
  // JSON Schema objects are plain objects with properties like 'type', 'properties', etc.
  if (schema === null || (typeof schema !== 'object' && typeof schema !== 'function')) {
    throw new Error(`Unsupported schema type: ${typeof schema}`);
  }

  // If it's a function that's not StandardSchemaWithJSON, it's not supported
  if (typeof schema === 'function') {
    throw new Error(`Unsupported schema type: function (schema libraries should implement StandardSchemaWithJSON)`);
  }

  return toStandardSchemaJsonSchema(schema as JSONSchema7);
}

/**
 * Type guard to check if a value implements the StandardSchemaV1 interface.
 *
 * @param value - The value to check
 * @returns True if the value implements StandardSchemaV1
 *
 * @example
 * ```typescript

View on GitHub (pinned to 75dd419e61)