mastra-ai/mastra · error · MastraError

WORKFLOW_SCHEMA_VALIDATION_FAILED

WORKFLOW_SCHEMA_VALIDATION_FAILED

Error message

Invalid ${type}: \n${validatedInputData.issues.map(e => `- ${e.path?.join('.')}: ${e.message}`).join('\n')}

What it means

`#validateSchema` runs the workflow's input/output schemas through the Standard Schema interface before use. If validation returns issues, Mastra throws this USER error listing each failing path and message prefixed by which side (e.g. 'input'/'output') failed.

Source

Thrown at packages/core/src/workflows/workflow.ts:3460

      const workflowsStore = await this.mastra?.getStorage()?.getStore('workflows');
      await workflowsStore?.updateWorkflowState({
        workflowName: this.workflowId,
        runId: this.runId,
        opts: {
          status: 'canceled',
        },
      });
    } catch {
      // Storage errors should not prevent cancellation from succeeding
      // The abort signal and in-memory status are already updated
    }
  }

  async #validateSchema<TInput>(schema: StandardSchemaWithJSON<TInput>, data: TInput, type: string) {
    const validatedInputData = await schema['~standard'].validate(data);

    if (validatedInputData.issues) {
      throw new MastraError({
        category: ErrorCategory.USER,
        domain: ErrorDomain.MASTRA_WORKFLOW,
        id: 'WORKFLOW_SCHEMA_VALIDATION_FAILED',
        text:
          `Invalid ${type}: \n` + validatedInputData.issues.map(e => `- ${e.path?.join('.')}: ${e.message}`).join('\n'),
        details: { type },
      });
    }

    return validatedInputData.value;
  }

  protected async _validateInput(inputData?: TInput) {
    if (!this.validateInputs || !this.inputSchema) {
      return inputData;
    }

    return this.#validateSchema(this.inputSchema, inputData, 'input data');

View on GitHub (pinned to 75dd419e61)

Solutions

Read the issue list in the message (`- path: message`) and fix the inputData fields accordingly.
Validate inputs client-side with the same schema (`schema.safeParse(inputData)`) before starting the run.
If the caller is correct and the schema changed unintentionally, revert/adjust the schema.
Use `z.input<typeof workflow.inputSchema>` to type your inputData so TypeScript catches drift.

Example fix

// before
await run.start({ inputData: { query } as any });
// after
const parsed = workflow.inputSchema.parse({ query });
await run.start({ inputData: parsed });

Defensive patterns

Strategy: validation

Validate before calling

const parsed = workflow.inputSchema.safeParse(inputData);
if (!parsed.success) {
  throw new Error(parsed.error.issues.map(i => `${i.path.join('.')}: ${i.message}`).join('\n'));
}
await run.start({ inputData: parsed.data });

Type guard

function isValidInput<S extends z.ZodTypeAny>(schema: S, data: unknown): data is z.infer<S> {
  return schema.safeParse(data).success;
}

Try / catch

try {
  await run.start({ inputData });
} catch (e) {
  if (e instanceof MastraError && e.id === 'WORKFLOW_SCHEMA_VALIDATION_FAILED') {
    console.error('fix inputs per issues:', e.message);
  } else throw e;
}

Prevention

Pre-parse inputData with the workflow's own schema before starting runs.
Type inputData using z.infer of the schema to catch drift at compile time.
Keep API payloads and schema in lockstep; bump schemas carefully.

When it happens

Trigger: Calling `run.start({ inputData })` (or observing a step whose schema validates output) with data that doesn't match the workflow/step Zod/Standard schema — missing required fields, wrong types, failed refinements.

Common situations: InputData typed loosely (any) drifting from the schema; API/CLI payloads missing required keys; schema tightened in a release while callers weren't updated; enum/refinement constraints violated.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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