apache/beam · error

Duplicate stage name

Error message

Duplicate stage name: "${uniqueName}". Use beam.withName(...) to give your transform a unique name.

What it means

preApplyTransform detected that a transform's stage name collides with an already-registered unique name. Beam derives stage names from transform names, and the runner keyed this pipeline's stage by that name; the duplicate is the transform being applied without an explicit distinct name.

Solutions

  1. Wrap the colliding transform in beam.withName('someUniqueName', ...) as the message suggests.
  2. Apply the same composite transform multiple times only via a loop variable or counter appended to withName so each application gets a distinct name.
  3. If names come from user config, sanitize/deduplicate them before applying transforms.
Defensive patterns

Strategy: validation

When it happens

Trigger: Thrown at sdks/typescript/src/apache_beam/internal/pipeline.ts:159 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/387deb8c3b7e7d2a. Report an issue: GitHub.

Appendix: source

Thrown at sdks/typescript/src/apache_beam/internal/pipeline.ts:159

    InputT extends pvalue.PValue<any>,
    OutputT extends pvalue.PValue<any>,
  >(transform: AsyncPTransformClass<InputT, OutputT>, input: InputT) {
    const this_ = this;
    const transformId = this.context.createUniqueName("transform");
    let parent: runnerApi.PTransform | undefined = undefined;
    if (this.transformStack.length) {
      parent =
        this.proto!.components!.transforms![
          this.transformStack[this.transformStack.length - 1]
        ];
      parent.subtransforms.push(transformId);
    } else {
      this.proto.rootTransformIds.push(transformId);
    }
    const uniqueName =
      (parent ? parent.uniqueName + "/" : "") + extractName(transform);
    if (this.usedStageNames.has(uniqueName)) {
      throw new Error(
        `Duplicate stage name: "${uniqueName}". ` +
          "Use beam.withName(...) to give your transform a unique name.",
      );
    }
    this.usedStageNames.add(uniqueName);
    const transformProto: runnerApi.PTransform = {
      uniqueName,
      subtransforms: [],
      inputs: objectMap(pvalue.flattenPValue(input), (pc) => pc.getId()),
      outputs: {},
      environmentId: this.defaultEnvironment,
      displayData: [],
      annotations: {},
    };
    this.proto.components!.transforms![transformId] = transformProto;
    return { id: transformId, proto: transformProto };
  }

View on GitHub (pinned to 12126d8942)