mastra-ai/mastra · error · HTTPException

error.message (workflow schema validation error)

Error message

error.message (workflow schema validation error)

What it means

handleError recognizes errors with id WORKFLOW_SCHEMA_VALIDATION_FAILED and rethrows them as HTTPException 400. This means the payload supplied to start or resume a workflow did not satisfy the workflow's input schema (Zod), so the request is rejected as a client error rather than crashing the run. The original error message (with schema detail) and stack are preserved for debugging.

Solutions

1. Validate the workflow input against its schema on the client before calling the endpoint (reuse the exported zod schema and call .parse() / .safeParse()).
2. Fix the offending fields named in the error message to match the expected types/shape.
3. If the schema changed intentionally, update the client payload generation to the new schema version.
4. Log the full error message/cause server-side; it includes the specific schema path that failed.

Example fix

// before: sending unvalidated input
const res = await fetch(url, { method: 'POST', body: JSON.stringify({ count: '3' }) });
// after: validate first
const input = workflowInputSchema.parse({ count: 3 }); // throws a precise ZodError locally
const res = await fetch(url, { method: 'POST', body: JSON.stringify(input) });

import { workflowInputSchema } from './workflows/my-workflow';
const parsed = workflowInputSchema.safeParse(input);
if (!parsed.success) {
  throw new Error('Invalid workflow input: ' + parsed.error.issues.map(i => `${i.path.join('.')}: ${i.message}`).join('; '));
}

function isSchemaValidationError(e: unknown): e is Error & { id: 'WORKFLOW_SCHEMA_VALIDATION_FAILED' } {
  return e instanceof Error && (e as any).id === 'WORKFLOW_SCHEMA_VALIDATION_FAILED';
}

try {
  await createAgentBuilderActionRun(actionId, input);
} catch (e) {
  if (isSchemaValidationError(e)) {
    showFieldErrors(parseIssuesFromMessage(e.message)); // guide user to fix input
    return;
  }
  throw e;
}

When it happens

Trigger: CREATE_AGENT_BUILDER_ACTION_RUN_ROUTE or STREAM_AGENT_BUILDER_ACTION_ROUTE invoked with input data that fails the workflow's zod input schema during start or resume.

Common situations: Frontend sends optional fields as undefined where the schema requires them; API version drift means the workflow schema gained new required fields; clients send stringified JSON where structured values (numbers, booleans) are expected.

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

• error.message (schema validation error, cause: field/errors)
• Cannot create workflow definition
• Extractor " " output did not match its schema
• Invalid structured content for tool
• OBSERVABILITY_INVALID_CONFIG

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

Appendix: source

Thrown at packages/server/src/server/handlers/error.ts:125

    throw new HTTPException(422, {
      res,
      message: error.message,
      cause: error,
    });
  }

  // A losing concurrent resume is a conflict on run state, not a malformed request, so it maps
  // to 409 and clients can distinguish it from a 400/500 and re-read the run.
  if (isWorkflowResumeAlreadyClaimedError(error)) {
    throw new HTTPException(409, {
      message: error.message,
      stack: error.stack,
      cause: error,
    });
  }

  if (isWorkflowSchemaValidationError(error)) {
    throw new HTTPException(400, {
      message: error.message,
      stack: error.stack,
      cause: error,
    });
  }

  const apiError = error as ApiError;

  const apiErrorStatus = apiError.status || apiError.details?.status || 500;

  throw new HTTPException(apiErrorStatus as StatusCode, {
    message: apiError.message || defaultMessage,
    stack: apiError.stack,
    cause: apiError.cause,
  });
}

View on GitHub (pinned to 75dd419e61)