{"record":{"id":"3935ee344cecbacf","repo":"mastra-ai/mastra","slug":"your-schema-is-async-which-is-not-supported-plea-3935ee","errorCode":null,"errorMessage":"Your schema is async, which is not supported. Please use a sync schema.","messagePattern":"Your schema is async, which is not supported\\. Please use a sync schema\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/tools/validation.ts","lineNumber":22,"sourceCode":"import type { PublicSchema, StandardSchemaWithJSON, StandardSchemaIssue } from '../schema';\nimport { getZodTypeName, isZodArray, isZodObject, unwrapZodType } from '../utils/zod-utils';\n\n/**\n * Safely validates data against a Standard Schema.\n * Catches internal Zod errors (like undefined union options) and provides better error messages.\n *\n * @param schema The Standard Schema to validate against\n * @param data The data to validate\n * @returns The validation result or throws with a descriptive error\n */\nfunction safeValidate<T>(\n  schema: StandardSchemaWithJSON<T>,\n  data: unknown,\n): { value: T } | { issues: readonly StandardSchemaIssue[] } {\n  try {\n    const result = schema['~standard'].validate(data);\n    if (result instanceof Promise) {\n      throw new Error('Your schema is async, which is not supported. Please use a sync schema.');\n    }\n    // Prioritise issues over value: Valibot returns both on failure (typed: false).\n    if ('issues' in result && Array.isArray(result.issues) && result.issues.length > 0) {\n      return { issues: result.issues as readonly StandardSchemaIssue[] };\n    }\n    return result as { value: T } | { issues: readonly StandardSchemaIssue[] };\n  } catch (err) {\n    // Catch Zod internal errors like \"Cannot read properties of undefined (reading 'run')\"\n    // This happens when a union schema has undefined options\n    if (err instanceof TypeError && err.message.includes('Cannot read properties of undefined')) {\n      throw new Error(\n        `Schema validation failed due to an invalid schema definition. ` +\n          `This often happens when a union schema (z.union or z.or) has undefined options. ` +\n          `Please check that all schema options are properly defined. Original error: ${err.message}`,\n      );\n    }\n    throw err;\n  }","sourceCodeStart":4,"sourceCodeEnd":40,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/tools/validation.ts#L4-L40","documentation":"`safeValidate` runs tool input/output/suspend-data validation through the Standard Schema interface and requires a synchronous result. If `schema['~standard'].validate(data)` returns a Promise, the schema performs async validation, which Mastra's tool validation path does not support, so it throws this error to fail fast with a clear message.","triggerScenarios":"Providing a tool `inputSchema`/`outputSchema`/suspend data schema with async refinements (`refine(async ...)`, `superRefine(async ...)`, async `.transform()`), so tool argument validation via `validation`/`coercedValidation`/`retryValidation` hits the Promise branch.","commonSituations":"Async uniqueness/DB checks in tool input schemas; schemas shared from HTTP handlers using async parsers; Zod 4 pipelines with async transforms copied from server code.","solutions":["Make the schema fully synchronous — remove async refinements/transforms from tool input/output schemas.","Perform async checks inside the tool's `execute` after sync shape validation passes.","If using `retryValidation`/coercion paths, confirm the fallback schema is also sync."],"exampleFix":"// before\ninputSchema: z.object({ id: z.string().refine(async id => !!(await db.find(id))) })\n// after\ninputSchema: z.object({ id: z.string() })\n// then in execute: const row = await db.find(context.id); if (!row) throw new Error(...)","handlingStrategy":"validation","validationCode":"function assertSyncToolSchema(schema: unknown) {\n  const res = (schema as any)?.['~standard']?.validate({});\n  if (res instanceof Promise) throw new Error('Tool input/output schema must be synchronous');\n}","typeGuard":"function isSyncStandardSchema(v: unknown): v is { '~standard': { validate: (v: unknown) => { value?: unknown; issues?: readonly unknown[] } } } {\n  try { return !((v as any)?.['~standard']?.validate({}) instanceof Promise); } catch { return false; }\n}","tryCatchPattern":"try {\n  await tool.execute({ context: args });\n} catch (e) {\n  if (e instanceof Error && e.message.includes('async, which is not supported')) {\n    console.error('Tool schema contains async validation; refactor to sync.');\n  }\n  throw e;\n}","preventionTips":["Audit tool schemas for `refine(async`, `superRefine(async`, and async `.transform()` during code review.","Run an early unit test that validates the schema synchronously and fails on Promise results.","Centralize async checks in a shared execute helper instead of embedding them in schemas."],"tags":["schema","validation","async","tools"],"backgroundTag":"async-schema-not-supported","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}