mastra-ai/mastra · error · Error

Uncommitted step flow changes detected. Call .commit() to re

Error message

Uncommitted step flow changes detected. Call .commit() to register the steps.

What it means

`createRun()` found steps defined in `stepFlow` but `this.executionGraph.steps` is unset, meaning `.commit()` was never called after the flow was built. Committing compiles the chained steps into the execution graph the runner executes; without it the graph is stale or empty. The error instructs the developer to call `.commit()` to register the steps.

Source

Thrown at packages/core/src/workflows/evented/workflow.ts:1728

  }

  __registerMastra(mastra: Mastra) {
    super.__registerMastra(mastra);
    this.executionEngine.__registerMastra(mastra);
  }

  async createRun(options?: {
    runId?: string;
    resourceId?: string;
    disableScorers?: boolean;
  }): Promise<Run<TEngineType, TSteps, TState, TInput, TOutput>> {
    if (this.stepFlow.length === 0) {
      throw new Error(
        'Execution flow of workflow is not defined. Add steps to the workflow via .then(), .branch(), etc.',
      );
    }
    if (!this.executionGraph.steps) {
      throw new Error('Uncommitted step flow changes detected. Call .commit() to register the steps.');
    }

    const runIdToUse = options?.runId || randomUUID();

    const workflowsStore = await this.mastra?.getStorage()?.getStore('workflows');

    const supportsConcurrentUpdates = workflowsStore?.supportsConcurrentUpdates?.() ?? false;
    if (workflowsStore && !supportsConcurrentUpdates) {
      throw new MastraError({
        id: 'ATOMIC_STORAGE_OPERATIONS_NOT_SUPPORTED',
        domain: ErrorDomain.MASTRA,
        category: ErrorCategory.USER,
        text:
          `Workflow "${this.id}" runs on the evented execution engine, which requires a storage adapter that supports concurrent updates. ` +
          `Your current workflow storage adapter does not. Switch to an adapter that does (for example @mastra/libsql), or, if you do not need scheduled execution, ` +
          `remove the \`schedule\` field from this workflow's definition to use the default execution engine.`,
        details: { workflowId: this.id },
      });

View on GitHub (pinned to 75dd419e61)

Solutions

1. Call `.commit()` after all step chaining, immediately before creating runs.
2. If steps are added dynamically, call `.commit()` again after the modifications and before the next run.
3. Centralize workflow construction in a factory that always ends with `.commit()` so it cannot be forgotten.

Example fix

// before
const wf = new Workflow({ id: 'pipeline', mastra });
wf.then(stepA).then(stepB);
await wf.start({ inputData }); // throws: uncommitted

// after
const wf = new Workflow({ id: 'pipeline', mastra });
wf.then(stepA).then(stepB).commit();
await wf.start({ inputData });

function assertCommitted(wf: Workflow): void {
  if ((wf as any).stepFlow?.length > 0 && !(wf as any).executionGraph?.steps) {
    throw new Error('Workflow steps defined but not committed; call .commit() before createRun()');
  }
}
assertCommitted(workflow);

function isCommitted(w: Workflow): boolean {
  return !!(w as any).executionGraph?.steps;
}

try {
  const run = workflow.createRun();
} catch (e) {
  if (e instanceof Error && e.message.includes('Uncommitted step flow changes')) {
    workflow.commit(); // then retry once
    return workflow.createRun();
  } else throw e;
}

When it happens

Trigger: Calling `createRun()`/`start()` after chaining steps (`.then()`, `.branch()`, ...) but before calling `.commit()`; or adding new steps to an already-committed workflow and re-running without re-committing (workflow.ts:1727-1730).

Common situations: Forgetting the `.commit()` terminal call when writing the workflow definition; conditionally appending steps at runtime and skipping commit; upgrading from older mastra versions where commit was implicit.

Related errors

• Uncommitted step flow changes detected. Call .commit() to re
• @mastra/livekit: `workflowInput` is required when `workflow`
• commit-failed
• LinearIntegration is not initialized — the factory binds sto
• save-workflow requires a Mastra context.

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