{"record":{"id":"2e32c15db31e3fb6","repo":"mastra-ai/mastra","slug":"uncommitted-step-flow-changes-detected-call-comm-2e32c1","errorCode":null,"errorMessage":"Uncommitted step flow changes detected. Call .commit() to register the steps.","messagePattern":"Uncommitted step flow changes detected\\. Call \\.commit\\(\\) to register the steps\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/workflows/workflow.ts","lineNumber":2560,"sourceCode":"    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 =\n      this.#runs.get(runIdToUse) ??\n      new Run({\n        workflowId: this.id,\n        stateSchema: this.stateSchema,\n        inputSchema: this.inputSchema,","sourceCodeStart":2542,"sourceCodeEnd":2578,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/workflows/workflow.ts#L2542-L2578","documentation":"Steps were added to the workflow (stepFlow is non-empty) but the resulting execution graph was not committed, so `executionGraph.steps` is missing. Mastra requires an explicit `.commit()` to freeze the step flow into an execution graph before any run can start.","triggerScenarios":"Calling createRun()/start() after `.then()`/`.branch()`/`.parallel()` calls without invoking `.commit()`; adding more steps after commit and re-running without committing again.","commonSituations":"New users unaware Mastra requires commit; dynamically appending steps at runtime then re-running; old code upgraded to versions enforcing commit.","solutions":["Call `.commit()` on the workflow after wiring all steps, before createRun/start.","If steps were appended after an earlier commit, re-commit.","Call commit once during module initialization right after the flow is fully defined.","Check any wrapper/factory that builds workflows returns them only after commit."],"exampleFix":"// before\nworkflow.then(a).then(b);\nconst run = await workflow.createRun();\n// after\nworkflow.then(a).then(b).commit();\nconst run = await workflow.createRun();","handlingStrategy":"validation","validationCode":"if ((workflow as any).stepFlow?.length && !(workflow as any).executionGraph?.steps) {\n  throw new Error('call workflow.commit() before createRun/start');\n}","typeGuard":"const isCommitted = (w: unknown): boolean =>\n  !!w && typeof w === 'object' && !!(w as any).executionGraph?.steps;","tryCatchPattern":"try {\n  const run = await workflow.createRun();\n} catch (e) {\n  if (e instanceof Error && e.message.includes('Uncommitted step flow changes')) {\n    (workflow as any).commit?.();\n    // retry createRun\n  } else throw e;\n}","preventionTips":["Adopt the habit: define steps -> commit -> createRun, in that order.","Re-commit whenever steps are added after initial commit.","Centralize workflow construction in factories that always commit."],"tags":["workflow","configuration","commit","execution-graph"],"backgroundTag":"workflow-not-committed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}