apache/beam · error · java.lang.IllegalArgumentException

Conflicting registrations for: %s

Error message

Conflicting registrations for: %s

What it means

ExpansionService.loadTransformBuilders scans the classpath for transform builders registered via META-INF services and throws IllegalArgumentException when two providers register builders under the same URN with conflicting implementations. It protects against ambiguous transform resolution at expansion time.

Source

Thrown at sdks/java/expansion-service/src/main/java/org/apache/beam/sdk/expansion/service/ExpansionService.java:232

            registrar.knownBuilderInstances().entrySet()) {

          String urn = entry.getKey();
          ExternalTransformBuilder newBuilder = entry.getValue();
          @Nullable ExternalTransformBuilder existingBuilder = registeredBuilders.get(urn);

          if (existingBuilder == null) {
            registeredBuilders.put(urn, newBuilder);
          } else {
            LOG.error(
                "Conflicting registrations for {}: {} and {}", urn, existingBuilder, newBuilder);
            conflictingRegistrations.add(urn);
          }
        }
      }

      Set<String> conflictingRegistrationSet = conflictingRegistrations.build();
      if (!conflictingRegistrationSet.isEmpty()) {
        throw new IllegalArgumentException(
            String.format(
                "Conflicting registrations for: %s",
                Joiner.on(", ").join(conflictingRegistrationSet)));
      }
      return registeredBuilders;
    }
  }

  private static class TransformProviderForPayloadTranslator<
          InputT extends PInput, OutputT extends POutput>
      implements TransformProvider<InputT, OutputT> {

    private final TransformPayloadTranslator<PTransform<InputT, OutputT>> payloadTranslator;

    // Returns true if the underlying transform represented by this is a schema-aware transform.
    private boolean isSchemaTransform() {
      return (payloadTranslator instanceof SchemaTransformPayloadTranslator);
    }

View on GitHub (pinned to 12126d8942)

Solutions

  1. Run `mvn dependency:tree` and exclude duplicate Beam IO/expansion jars
  2. Remove or align versions of conflicting expansion service dependencies
  3. Check META-INF/services/org.apache.beam.model.expansion.v1.ExpansionService files for duplicates
  4. If intentional, use one consolidated expansion service or shade/merge service files properly

Example fix

// before
<dependency><groupId>org.apache.beam</groupId><artifactId>beam-sdks-java-io-jdbc</artifactId><version>2.40.0</version></dependency>
<dependency><groupId>org.apache.beam</groupId><artifactId>beam-sdks-java-io-jdbc</artifactId><version>2.50.0</version></dependency>
// after
<dependency>
  <groupId>org.apache.beam</groupId>
  <artifactId>beam-sdks-java-io-jdbc</artifactId>
  <version>2.50.0</version>
</dependency>
Defensive patterns

Strategy: validation

Validate before calling

Map<String, String> urns = new HashMap<>();
// before starting service, scan META-INF/services entries for duplicate URNs and fail early

Try / catch

try { expansionService.start(); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Conflicting registrations")) { /* dedupe classpath */ } throw e; }

Prevention

When it happens

Trigger: Starting an ExpansionService (or calling registeredBuilders) when the classpath contains multiple expansion service providers claiming the same transform URN with different builder implementations.

Common situations: Multiple Beam expansion JARs on the classpath (e.g., two versions of beam-sdks-java-io-... or beam-runners-...); fat JARs bundling duplicate service files; adding a connector already included in the expansion service bundle.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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