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.

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)

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)
• OBSERVABILITY_INVALID_CONFIG
• OBSERVABILITY_INVALID_INSTANCE_CONFIG
• Cannot create workflow definition "${input.id}": inputSchema
• WORKFLOW_SCHEMA_VALIDATION_FAILED

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