apache/beam · error · IllegalArgumentException

Specified path '%s' already used for subcomponent %s. Subcom

Error message

Specified path '%s' already used for subcomponent %s. Subcomponents must be included using unique paths.

What it means

When a component includes subcomponents via includeSubcomponent(), each subcomponent must be registered under a unique path. Beam tracks visited components by absolute path; if the same path is reused for a different subcomponent, it throws an IllegalArgumentException with this message to prevent ambiguous display-data hierarchies.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/display/DisplayData.java:727

    private @Nullable Path latestPath;
    private @Nullable Class<?> latestNs;

    private InternalBuilder() {
      this.entries = Maps.newHashMap();
      this.visitedComponents = Sets.newIdentityHashSet();
      this.visitedPathMap = Maps.newHashMap();
    }

    @Override
    public Builder include(String path, HasDisplayData subComponent) {
      checkNotNull(subComponent, "subComponent argument cannot be null");
      checkNotNull(path, "path argument cannot be null");

      Path absolutePath = latestPath.extend(path);

      HasDisplayData existingComponent = visitedPathMap.get(absolutePath);
      if (existingComponent != null) {
        throw new IllegalArgumentException(
            String.format(
                "Specified path '%s' already used for "
                    + "subcomponent %s. Subcomponents must be included using unique paths.",
                path, existingComponent));
      }

      return include(absolutePath, subComponent);
    }

    @Override
    public Builder delegate(HasDisplayData component) {
      checkNotNull(component);

      return include(latestPath, component);
    }

    private Builder include(Path path, HasDisplayData subComponent) {
      if (visitedComponents.contains(subComponent)) {

View on GitHub (pinned to 12126d8942)

Solutions

Make each path unique, e.g. include("subcomponent-" + i, subComponent) in loops
Audit includeSubcomponent calls for duplicated literal path strings
Namespace paths by component class or instance id
Add a unit test asserting populateDisplayData runs without IllegalArgumentException

Example fix

// before
for (Transform t : transforms) { builder.include("subcomponent", t); }
// after
for (int i = 0; i < transforms.size(); i++) { builder.include("subcomponent-" + i, transforms.get(i)); }

Defensive patterns

Strategy: validation

Validate before calling

Set<String> usedPaths = new HashSet<>();
String path = ...;
if (!usedPaths.add(path)) { throw new IllegalStateException("Duplicate subcomponent path: " + path); }

Try / catch

try { builder.include(path, subComponent); } catch (IllegalArgumentException e) { /* log duplicate path and skip */ }

Prevention

Generate paths with indices/ids when including subcomponents in loops
Never reuse literal path strings across includeSubcomponent calls
Test populateDisplayData for transforms with multiple subcomponents

When it happens

Trigger: Calling builder.include("key", subComponent1) and later builder.include("key", subComponent2) in the same populateDisplayData tree, or including the same path in a loop where the path argument is constant instead of indexed.

Common situations: Looping over a list of sub-transforms and calling include("subcomponent", x) with the same literal path each iteration; merging display data from multiple sources that reuse path names.

Related errors

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