{"record":{"id":"856079f92437c9a1","repo":"mastra-ai/mastra","slug":"workflow-definition-graph-must-be-an-array","errorCode":null,"errorMessage":"Workflow definition graph must be an array.","messagePattern":"Workflow definition graph must be an array\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/workflows/builder/index.ts","lineNumber":203,"sourceCode":"  }\n  if ((normalized.type === 'parallel' || normalized.type === 'conditional') && Array.isArray(normalized.steps)) {\n    normalized.steps = normalized.steps.map(step =>\n      normalizeEntry(step as Record<string, unknown>),\n    ) as unknown as WorkflowBuilderJsonValue[];\n  }\n  if ((normalized.type === 'foreach' || normalized.type === 'loop') && normalized.step) {\n    normalized.step = normalizeEntry(normalized.step as Record<string, unknown>) as unknown as WorkflowBuilderJsonValue;\n  }\n  return normalized as unknown as WorkflowBuilderGraphEntry;\n}\n\nexport function normalizeWorkflowBuilderDefinition(input: unknown): WorkflowBuilderDefinition {\n  const normalized = normalizeJsonValue(input, 'workflow definition', new Set()) as WorkflowBuilderJsonObject;\n  if (normalized.description === null) delete normalized.description;\n  if (normalized.metadata === null) delete normalized.metadata;\n  if (normalized.stateSchema === null) delete normalized.stateSchema;\n  if (normalized.requestContextSchema === null) delete normalized.requestContextSchema;\n  if (!Array.isArray(normalized.graph)) throw new TypeError('Workflow definition graph must be an array.');\n  normalized.graph = normalized.graph.map(entry =>\n    normalizeEntry(entry as Record<string, unknown>),\n  ) as unknown as WorkflowBuilderJsonValue[];\n  return normalized as unknown as WorkflowBuilderDefinition;\n}\n\nexport * from './preflight';\nexport * from './inspection';\nexport * from './authoring-schema';\nexport * from './agent';\n","sourceCodeStart":185,"sourceCodeEnd":214,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/workflows/builder/index.ts#L185-L214","documentation":"normalizeWorkflowBuilderDefinition first JSON-normalizes the input, then requires `graph` to be an array of step entries. If graph is missing or of another type (object, string, null after deletion), this TypeError is thrown because the workflow's step list cannot be processed.","triggerScenarios":"Calling normalizeWorkflowBuilderDefinition or createWorkflow with a definition whose `graph` field is undefined, null, an object, or a string — e.g. a hand-written definition `{ id, name, steps: [...] }` that uses the wrong key instead of `graph`.","commonSituations":"Hand-authoring serialized workflow definitions with the wrong property name; loading a stored definition from an older schema version that used a different field; a migration that dropped `graph`; JSON deserialization that omitted the field.","solutions":["Ensure the definition includes `graph` as an array of step entries.","Fix the property name (e.g. rename `steps`/`flow` to `graph`) when hand-writing or migrating definitions.","Validate stored definitions against the current schema before calling normalizeWorkflowBuilderDefinition, and prefer the builder API (createWorkflow + .then/.map) over hand-built definitions."],"exampleFix":"// before\nconst def = { id: 'w', name: 'W', steps: [{ type: 'step', id: 'a' }] };\nnormalizeWorkflowBuilderDefinition(def);\n// after\nconst def = { id: 'w', name: 'W', graph: [{ type: 'step', id: 'a' }] };\nnormalizeWorkflowBuilderDefinition(def);","handlingStrategy":"validation","validationCode":"function isValidDefinition(def) {\n  return def != null && typeof def === 'object' && Array.isArray(def.graph);\n}\nif (!isValidDefinition(input)) throw new TypeError('Definition must have a graph array');","typeGuard":"function isWorkflowBuilderDefinition(d: unknown): d is { graph: unknown[] } & Record<string, unknown> {\n  return typeof d === 'object' && d !== null && Array.isArray((d as any).graph);\n}","tryCatchPattern":"try {\n  const def = normalizeWorkflowBuilderDefinition(input);\n} catch (e) {\n  if (e instanceof TypeError && e.message.includes('graph must be an array')) {\n    // repair/replace definition or surface a config error\n  }\n  throw e;\n}","preventionTips":["Always build definitions via the builder API rather than hand-writing objects.","Key the step list as `graph`, not `steps` or `flow`.","Validate persisted definitions against the current schema after migrations.","Write a round-trip test: normalize → serialize → normalize."],"tags":["validation","workflow","schema"],"backgroundTag":"schema-validation-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}