apache/beam · error · IllegalStateException

Pipeline update will not be possible because the following t

Error message

Pipeline update will not be possible because the following transforms do not have stable unique names: %s.

Conflicting instances:
%s

You can fix it adding a name when you call apply(): pipeline.apply(<name>, <transform>).

What it means

Pipeline.validate() checks that all transforms have stable unique names (controlled by options.getStableUniqueNames(), default CHECK_WARNING). In ERROR mode, when multiple transforms share the same generated name, it throws this verbose IllegalStateException listing conflicts, because pipeline update (job replacement) requires deterministic transform names.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/Pipeline.java:623

    }
  }

  @VisibleForTesting
  void validate(PipelineOptions options) {
    this.traverseTopologically(new ValidateVisitor(options));
    final Collection<Map.Entry<String, Collection<PTransform<?, ?>>>> errors =
        Collections2.filter(instancePerName.asMap().entrySet(), Predicates.not(new IsUnique<>()));
    if (!errors.isEmpty()) {
      switch (options.getStableUniqueNames()) {
        case OFF:
          break;
        case WARNING:
          LOG.warn(
              "The following transforms do not have stable unique names: {}",
              Joiner.on(", ").join(transform(errors, new KeysExtractor())));
          break;
        case ERROR: // be very verbose here since it will just fail the execution
          throw new IllegalStateException(
              String.format(
                      "Pipeline update will not be possible because the following transforms do"
                          + " not have stable unique names: %s.",
                      Joiner.on(", ").join(transform(errors, new KeysExtractor())))
                  + "\n\n"
                  + "Conflicting instances:\n"
                  + Joiner.on("\n")
                      .join(transform(errors, new UnstableNameToMessage(instancePerName)))
                  + "\n\nYou can fix it adding a name when you call apply(): "
                  + "pipeline.apply(<name>, <transform>).");
        default:
          throw new IllegalArgumentException(
              "Unrecognized value for stable unique names: " + options.getStableUniqueNames());
      }
    }
  }

  /**

View on GitHub (pinned to 12126d8942)

Solutions

1. Give each transform an explicit name: pipeline.apply("UniqueName", transform) or setLabel().
2. Generate deterministic names programmatically (e.g. include loop index) when transforms are created in loops.
3. Relax to --stableUniqueNames=CHECK_WARNING or WARNING if you don't need pipeline update (less safe).
4. Review the 'Conflicting instances' list in the message to find exactly which transforms collide and rename them.

Example fix

// before
// pipeline.apply(MapElements.via(...)); // in a loop -> duplicate name 'MapElements'
// after
// pipeline.apply("MapStep-" + i, MapElements.via(...));

// Java: pre-validate transform names before run
Map<String, Integer> counts = new HashMap<>();
pipeline.traverseTopologically(new PipelineVisitor.Defaults() {
  @Override public void visitPrimitiveTransform(Node n) { counts.merge(n.getName(), 1, Integer::sum); }
});
List<String> dupes = counts.entrySet().stream().filter(e -> e.getValue() > 1).map(Map.Entry::getKey).collect(toList());
if (!dupes.isEmpty()) throw new IllegalArgumentException("Duplicate transform names: " + dupes);

try {
  pipeline.run();
} catch (IllegalStateException e) {
  if (e.getMessage().contains("stable unique names")) {
    throw new IllegalArgumentException("Add explicit apply(name, transform) labels: " + e.getMessage());
  }
  throw e;
}

When it happens

Trigger: Running with --stableUniqueNames=ERROR while two or more transforms produce identical names — typically repeated identical PTransforms applied in a loop without explicit names, so Beam appends nondeterministic suffixes or collides.

Common situations: Teams enabling stable unique names to use pipeline update / stateful reruns; generated pipelines built programmatically where transforms are applied inside loops; anonymous lambdas combined into same-named transforms.

Related errors

• Failed to validate transform %s
• Illegal access to pipeline after visitor traversal was compl
• One or more ErrorHandlers aren't closed, and this pipeline c
• Failed to validate %s
• Failed to validate %s

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