{"record":{"id":"a3fea1ae789bb664","repo":"mastra-ai/mastra","slug":"error-message-workflow-schema-validation-error","errorCode":null,"errorMessage":"error.message (workflow schema validation error)","messagePattern":"error\\.message \\(workflow schema validation error\\)","errorType":"http","errorClass":"HTTPException","httpStatus":400,"severity":"error","filePath":"packages/server/src/server/handlers/error.ts","lineNumber":125,"sourceCode":"    throw new HTTPException(422, {\n      res,\n      message: error.message,\n      cause: error,\n    });\n  }\n\n  // A losing concurrent resume is a conflict on run state, not a malformed request, so it maps\n  // to 409 and clients can distinguish it from a 400/500 and re-read the run.\n  if (isWorkflowResumeAlreadyClaimedError(error)) {\n    throw new HTTPException(409, {\n      message: error.message,\n      stack: error.stack,\n      cause: error,\n    });\n  }\n\n  if (isWorkflowSchemaValidationError(error)) {\n    throw new HTTPException(400, {\n      message: error.message,\n      stack: error.stack,\n      cause: error,\n    });\n  }\n\n  const apiError = error as ApiError;\n\n  const apiErrorStatus = apiError.status || apiError.details?.status || 500;\n\n  throw new HTTPException(apiErrorStatus as StatusCode, {\n    message: apiError.message || defaultMessage,\n    stack: apiError.stack,\n    cause: apiError.cause,\n  });\n}\n","sourceCodeStart":107,"sourceCodeEnd":142,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/error.ts#L107-L142","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Validate the workflow input against its schema on the client before calling the endpoint (reuse the exported zod schema and call .parse() / .safeParse()).","Fix the offending fields named in the error message to match the expected types/shape.","If the schema changed intentionally, update the client payload generation to the new schema version.","Log the full error message/cause server-side; it includes the specific schema path that failed."],"exampleFix":"// before: sending unvalidated input\nconst res = await fetch(url, { method: 'POST', body: JSON.stringify({ count: '3' }) });\n// after: validate first\nconst input = workflowInputSchema.parse({ count: 3 }); // throws a precise ZodError locally\nconst res = await fetch(url, { method: 'POST', body: JSON.stringify(input) });","handlingStrategy":"validation","validationCode":"import { workflowInputSchema } from './workflows/my-workflow';\nconst parsed = workflowInputSchema.safeParse(input);\nif (!parsed.success) {\n  throw new Error('Invalid workflow input: ' + parsed.error.issues.map(i => `${i.path.join('.')}: ${i.message}`).join('; '));\n}","typeGuard":"function isSchemaValidationError(e: unknown): e is Error & { id: 'WORKFLOW_SCHEMA_VALIDATION_FAILED' } {\n  return e instanceof Error && (e as any).id === 'WORKFLOW_SCHEMA_VALIDATION_FAILED';\n}","tryCatchPattern":"try {\n  await createAgentBuilderActionRun(actionId, input);\n} catch (e) {\n  if (isSchemaValidationError(e)) {\n    showFieldErrors(parseIssuesFromMessage(e.message)); // guide user to fix input\n    return;\n  }\n  throw e;\n}","preventionTips":["Reuse the workflow's exported zod schema on the client to validate input before every start/resume call.","Regenerate/refresh client payload builders whenever workflow schemas change.","Add shared schema types so TypeScript catches shape drift at compile time."],"tags":["http-400","schema-validation","workflow","zod"],"backgroundTag":"schema-validation-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}