{"record":{"id":"f791ff6985685f00","repo":"mastra-ai/mastra","slug":"execution-flow-of-workflow-is-not-defined-add-ste-f791ff","errorCode":null,"errorMessage":"Execution flow of workflow is not defined. Add steps to the workflow via .then(), .branch(), etc.","messagePattern":"Execution flow of workflow is not defined\\. Add steps to the workflow via \\.then\\(\\), \\.branch\\(\\), etc\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/workflows/workflow.ts","lineNumber":2555,"sourceCode":"   * @returns A Run instance that can be used to execute the workflow\n   */\n  async createRun(options?: {\n    runId?: string;\n    resourceId?: string;\n    disableScorers?: boolean;\n    /** Optional pubsub instance for streaming events. If not provided, a new EventEmitterPubSub is created. */\n    pubsub?: PubSub;\n    /**\n     * Overrides the workflow-wide `shouldPersistSnapshot` option for this run only.\n     * Used for transient runs that must never touch storage even when the workflow\n     * persists normally (e.g. per-chunk agent output-processor runs, #19605).\n     */\n    shouldPersistSnapshot?: WorkflowOptions['shouldPersistSnapshot'];\n    /** Overrides the workflow-wide tracing policy for this run only. */\n    tracingPolicy?: TracingPolicy;\n  }): Promise<Run<TEngineType, TSteps, TState, TInput, TOutput, TRequestContext>> {\n    if (this.stepFlow.length === 0) {\n      throw new Error(\n        'Execution flow of workflow is not defined. Add steps to the workflow via .then(), .branch(), etc.',\n      );\n    }\n    if (!this.executionGraph.steps) {\n      throw new Error('Uncommitted step flow changes detected. Call .commit() to register the steps.');\n    }\n    const runIdToUse =\n      options?.runId ||\n      this.#mastra?.generateId({\n        idType: 'run',\n        source: 'workflow',\n        entityId: this.id,\n        resourceId: options?.resourceId,\n      }) ||\n      randomUUID();\n\n    // Return a new Run instance with object parameters\n    const run =","sourceCodeStart":2537,"sourceCodeEnd":2573,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/workflows/workflow.ts#L2537-L2573","documentation":"A workflow run is attempted while `stepFlow` is empty, meaning no execution flow (steps) has been defined. Mastra refuses to start a run with nothing to execute, and throws a plain Error instructing you to compose the workflow with `.then()`, `.branch()`, `.parallel()`, etc.","triggerScenarios":"Calling `workflow.createRun()` or `workflow.start()` on a workflow constructed as `new Workflow({ id, ... })` with no `.then(step)`/`.branch(...)`/`.parallel(...)` calls; steps added only conditionally so the flow ended up empty.","commonSituations":"Boilerplate workflows created but never wired; conditional assembly where all branch conditions skipped adding steps; refactoring that removed all steps; instantiating a subclass that forgot to define the flow.","solutions":["Add at least one step: `workflow.then(myStep)` before calling createRun/start.","Review the workflow definition path — ensure the code adding steps actually executes (not behind a false condition).","If the workflow is intentionally empty, don't run it; guard the caller.","Commit the flow after wiring steps (see related Uncommitted-step-flow error)."],"exampleFix":"// before\nconst workflow = new Workflow({ id: 'empty' });\nconst run = await workflow.createRun();\n// after\nconst workflow = new Workflow({ id: 'w' });\nworkflow.then(fetchStep).then(processStep).commit();\nconst run = await workflow.createRun();","handlingStrategy":"validation","validationCode":"if (!workflow || (workflow as any).stepFlow?.length === 0) {\n  throw new Error('workflow has no steps; add .then()/.branch() before createRun');\n}","typeGuard":"const isRunnable = (w: unknown): w is { createRun: () => unknown } =>\n  !!w && typeof w === 'object' && 'createRun' in w && Array.isArray((w as any).stepFlow) && (w as any).stepFlow.length > 0;","tryCatchPattern":"try {\n  const run = await workflow.createRun();\n} catch (e) {\n  if (e instanceof Error && e.message.includes('Execution flow of workflow is not defined')) {\n    // build the flow programmatically before running\n  } else throw e;\n}","preventionTips":["Always wire at least one step immediately after constructing a workflow.","Avoid conditionally omitting all steps when building flows dynamically.","Call .commit() in the same factory that builds the workflow."],"tags":["workflow","configuration","missing-steps"],"backgroundTag":"workflow-not-defined","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}