anomalyco/sst · error · Error

Multiple states with the same name "${this.name}". State nam

Error message

Multiple states with the same name "${this.name}". State names must be unique.

What it means

AWS Step Functions requires every state name within a state machine to be unique, since names become the ASL state keys. SST's `State.assertStateNameUnique` (platform/src/components/aws/step-functions/state.ts:291) walks the whole graph (next states, catch targets, and Parallel/Map child graphs) at synth time and throws if two distinct State instances share the same `name`.

Source

Thrown at platform/src/components/aws/step-functions/state.ts:294

      this._prevState?.getRoot() ?? this._parentGraphState?.getRoot() ?? this
    );
  }

  /**
   * @internal
   */
  public getHead(): State {
    return this._prevState?.getHead() ?? this;
  }

  /**
   * Assert that the state name is unique.
   * @internal
   */
  public assertStateNameUnique(states: Map<string, State> = new Map()) {
    const existing = states.get(this.name);
    if (existing && existing !== this)
      throw new Error(
        `Multiple states with the same name "${this.name}". State names must be unique.`,
      );

    states.set(this.name, this);

    this._nextState?.assertStateNameUnique(states);
    this._catches?.forEach((c) => c.next.assertStateNameUnique(states));
    this._childGraphStates.forEach((c) => c.assertStateNameUnique(states));
  }

  /**
   * Assert that the state is not reused.
   * @internal
   */
  public assertStateNotReused(
    states: Map<State, string> = new Map(),
    graphId: string = "main",
  ) {

View on GitHub (pinned to a0bd20f762)

Solutions

1. Rename one of the states so every name in the machine is unique.
2. If states are generated in a loop, interpolate a unique suffix into the name, e.g. `name: \`Process-${i}\`.`
3. If two branches genuinely need identical logic, define a separate state instance per branch with a distinct name rather than sharing one.

Example fix

// before
const a = new sst.aws.StepFunctionsTask("Process", { ... });
const b = new sst.aws.StepFunctionsTask("Process", { ... });

// after
const a = new sst.aws.StepFunctionsTask("ProcessA", { ... });
const b = new sst.aws.StepFunctionsTask("ProcessB", { ... });

const names = new Set<string>();
function assertUniqueName(state: { name: string }) {
  if (names.has(state.name))
    throw new Error(`duplicate state name: ${state.name}`);
  names.add(state.name);
}

null

try {
  const machine = new sst.aws.StepFunctions("MyMachine", { state: root });
} catch (err) {
  if (String(err).includes("must be unique")) {
    console.error("Duplicate state name — rename one of the states");
  } else throw err;
}

When it happens

Trigger: Creating two State instances (tasks, choices, etc.) with the same `name` argument in the same StepFunctions state machine, e.g. two `new sst.aws.StepFunctionsTask("Process", ...)` in different branches of a Parallel/Map graph, then chaining or adding them to one machine.

Common situations: Programmatically generating states in a loop without varying the name; duplicating a chain snippet across Parallel branches; copy-pasting a state definition into a Catch path.

Related errors

• The "${this.name}" state already has a next state. States ca
• Cannot reuse the "${this.name}" state. States cannot be reus
• Component name "${args.name}" is reserved. Please choose a d
• Component name ${args.name} is not unique.
• invalid archive name format: %s

AI-assisted analysis of anomalyco/sst@a0bd20f762 (2026-08-30). Data as JSON: /api/errors/fdcdc7cf8bf4daae. Report an issue: GitHub.