What causes "We could not convert the schema to a JSONSchema" in mastra-ai/mastra?

Simplify the schema: replace custom transforms/unsupported types with plain Zod objects/arrays/primitives

mastra-ai/mastra · error · Error

We could not convert the schema to a JSONSchema

Error message

We could not convert the schema to a JSONSchema

What it means

schemaToJsonSchema converts a (Zod v4) schema to JSON Schema via toStandardSchema + standardSchemaToJSONSchema. If either conversion throws for any reason, the original error is swallowed and a generic Error 'We could not convert the schema to a JSONSchema' is raised. Callers listed (workflowList, toolList, workflowStep, finalResult) use it to build completion feedback schemas.

Source

Thrown at packages/core/src/loop/network/index.ts:45

import { createStep } from '../../workflows/workflow';
import { PRIMITIVE_TYPES } from '../types';
import { pruneAgentLoopSnapshot } from '../workflows/prune-snapshot';

/**
 * Convert a schema (PublicSchema) to JSON Schema.
 * Handles Zod v4, AI SDK schemas, JSON Schema, and StandardSchemaWithJSON.
 */
function schemaToJsonSchema(schema: PublicSchema): unknown {
  if (isStandardSchemaWithJSON(schema)) {
    return standardSchemaToJSONSchema(schema);
  }

  // Try to convert raw Zod v4 schema to StandardSchema
  try {
    const standardSchema = toStandardSchema(schema);
    return standardSchemaToJSONSchema(standardSchema);
  } catch {
    throw new Error('We could not convert the schema to a JSONSchema');
  }
}
import type { CompletionConfig, CompletionContext } from './validation';
import {
  runValidation,
  formatCompletionFeedback,
  runDefaultCompletionCheck,
  generateFinalResult,
  generateStructuredFinalResult,
} from './validation';

const OBSERVATIONAL_MEMORY_NETWORK_ERROR =
  'Observational Memory is not supported with agent network. Agent network does not propagate the threadId/resourceId context Observational Memory requires. Disable observationalMemory before using agent.network().';

function isObservationalMemoryEnabled(config: unknown): boolean {
  if (config === true) return true;
  if (!config || config === false) return false;
  if (typeof config !== 'object') return false;

View on GitHub (pinned to 75dd419e61)

Solutions

Simplify the schema: replace custom transforms/unsupported types with plain Zod objects/arrays/primitives
Confirm you are using Zod v4 schemas as expected by this code path
Debug by calling toStandardSchema(schema) yourself to see the swallowed original error
If you already have JSON Schema, use an API path that accepts JSON Schema directly

Example fix

// before
const schema = z.object({
  id: z.string().transform(s => s.trim()),
}); // transform breaks conversion
// after
const schema = z.object({
  id: z.string(),
}); // convert after validation instead

Defensive patterns

Strategy: try-catch

Validate before calling

// Sanity-check the schema is a Zod object before conversion
import { z } from 'zod';
if (!(schema instanceof z.ZodType)) {
  throw new Error('Expected a Zod v4 schema');
}

Type guard

import { z } from 'zod';
function isZodSchema(v: unknown): v is z.ZodType {
  return v instanceof z.ZodType;
}

Try / catch

try {
  const jsonSchema = schemaToJsonSchema(schema);
} catch (e) {
  if (e instanceof Error && e.message.includes('could not convert the schema')) {
    // original cause was swallowed; re-convert manually to surface it
    const std = toStandardSchema(schema); // throws the real error
    console.error('Schema conversion failed at:', std);
  }
  throw e;
}

Prevention

Keep tool/workflow parameter schemas to plain Zod v4 object/array/primitive types
Avoid transforms, refinements with unsupported internals, and branded types in schema boundaries
Pin Zod v4 and test schema conversion in CI for each tool/workflow you register
Re-run toStandardSchema yourself when debugging — the thrown message swallows the root cause

When it happens

Trigger: Passing a schema that toStandardSchema or standardSchemaToJSONSchema cannot handle: unsupported Zod types/transforms, a non-Zod object passed as a schema, cyclic references, or a schema built with features unsupported by the converter.

Common situations: Using advanced Zod v4 features (custom transforms, branded types with unsupported internals) in tool/workflow parameter schemas; passing a Zod v3 schema or plain JSON Schema object where Zod v4 is expected; typo passing the wrong variable as the schema.

Related errors

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