{"record":{"id":"fdcdc7cf8bf4daae","repo":"anomalyco/sst","slug":"multiple-states-with-the-same-name-this-name","errorCode":null,"errorMessage":"Multiple states with the same name \"${this.name}\". State names must be unique.","messagePattern":"Multiple states with the same name \"(.+?)\"\\. State names must be unique\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"platform/src/components/aws/step-functions/state.ts","lineNumber":294,"sourceCode":"      this._prevState?.getRoot() ?? this._parentGraphState?.getRoot() ?? this\n    );\n  }\n\n  /**\n   * @internal\n   */\n  public getHead(): State {\n    return this._prevState?.getHead() ?? this;\n  }\n\n  /**\n   * Assert that the state name is unique.\n   * @internal\n   */\n  public assertStateNameUnique(states: Map<string, State> = new Map()) {\n    const existing = states.get(this.name);\n    if (existing && existing !== this)\n      throw new Error(\n        `Multiple states with the same name \"${this.name}\". State names must be unique.`,\n      );\n\n    states.set(this.name, this);\n\n    this._nextState?.assertStateNameUnique(states);\n    this._catches?.forEach((c) => c.next.assertStateNameUnique(states));\n    this._childGraphStates.forEach((c) => c.assertStateNameUnique(states));\n  }\n\n  /**\n   * Assert that the state is not reused.\n   * @internal\n   */\n  public assertStateNotReused(\n    states: Map<State, string> = new Map(),\n    graphId: string = \"main\",\n  ) {","sourceCodeStart":276,"sourceCodeEnd":312,"githubUrl":"https://github.com/anomalyco/sst/blob/a0bd20f762883e72a35caccb4896c42ce5b3f707/platform/src/components/aws/step-functions/state.ts#L276-L312","documentation":"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`.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Rename one of the states so every name in the machine is unique.","If states are generated in a loop, interpolate a unique suffix into the name, e.g. `name: \\`Process-${i}\\`.`","If two branches genuinely need identical logic, define a separate state instance per branch with a distinct name rather than sharing one."],"exampleFix":"// before\nconst a = new sst.aws.StepFunctionsTask(\"Process\", { ... });\nconst b = new sst.aws.StepFunctionsTask(\"Process\", { ... });\n\n// after\nconst a = new sst.aws.StepFunctionsTask(\"ProcessA\", { ... });\nconst b = new sst.aws.StepFunctionsTask(\"ProcessB\", { ... });","handlingStrategy":"validation","validationCode":"const names = new Set<string>();\nfunction assertUniqueName(state: { name: string }) {\n  if (names.has(state.name))\n    throw new Error(`duplicate state name: ${state.name}`);\n  names.add(state.name);\n}","typeGuard":"null","tryCatchPattern":"try {\n  const machine = new sst.aws.StepFunctions(\"MyMachine\", { state: root });\n} catch (err) {\n  if (String(err).includes(\"must be unique\")) {\n    console.error(\"Duplicate state name — rename one of the states\");\n  } else throw err;\n}","preventionTips":["Derive state names from unique identifiers (loop index, branch id) when generating states programmatically.","Adopt a naming convention that includes the branch/role, e.g. `Process-Success`, `Process-Failure`.","Search your config for repeated `new ...(\"SameName\")` before deploying."],"tags":["step-functions","state-machine","naming"],"backgroundTag":"duplicate-state-name","analyzedSha":"a0bd20f762883e72a35caccb4896c42ce5b3f707","analyzedAt":"2026-08-30T11:26:00.383Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}