apache/beam · error · java.lang.IllegalArgumentException

Conflicting registrations for

Error message

Conflicting registrations for: %s

What it means

loadTransformPayloadTranslators aggregates PTransformPayloadTranslators via ServiceLoader and detects when two translators claim the same PTransform class. If the conflicting-registration set is non-empty, this IllegalArgumentException lists the conflicting classes, indicating a duplicate/ambiguous translator registration on the classpath.

Solutions

  1. Remove one of the duplicate translator registrations (delete the older/duplicate jar from the classpath).
  2. Run `mvn dependency:tree` (or equivalent) to find duplicate Beam/transform-library artifacts and exclude one.
  3. Ensure only one META-INF/services file per translator class exists across shaded jars; fix shade plugin resource filtering.
  4. If intentional override is desired, register the translator in the built-in override list rather than alongside.

Example fix

// before
<dependency>org.example:custom-beam-transforms:1.0</dependency>
<dependency>org.example:custom-beam-transforms:2.0</dependency> // both register translators
// after: keep exactly one
<dependency>org.example:custom-beam-transforms:2.0</dependency>
Defensive patterns

Strategy: validation

Validate before calling

// inspect duplicate ServiceLoader registrations at startup
Set<String> classes = new HashSet<>();
for (PTransformPayloadTranslator t : ServiceLoader.load(PTransformPayloadTranslator.class)) { if (!classes.add(t.getClass().getName())) log.warn("duplicate translator: " + t.getClass()); }

Try / catch

try { PTransformTranslation.getKnownPayloadTranslators(); } catch (IllegalArgumentException e) { /* conflicting registrations: dedupe classpath */ throw e; }

Prevention

When it happens

Trigger: Multiple jars on the classpath each provide a ServiceLoader-registered translator for the same PTransform subclass (e.g. two versions of a custom transform library, or a vendored copy of Beam's own translators alongside the official one).

Common situations: Duplicate Beam SDK versions on the classpath; shading/packaging that includes both a library and its vendored translator; two plugins registering translators for the same custom transform.

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/beca63562dc030dc. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/util/construction/PTransformTranslation.java:471

        TransformPayloadTranslator newTranslator = entry.getValue();
        @Nullable TransformPayloadTranslator existingTranslator = translators.get(ptransformClass);

        if (existingTranslator == null) {
          translators.put(ptransformClass, newTranslator);
        } else {
          LOG.error(
              "Conflicting registrations for {}: {} and {}",
              ptransformClass,
              existingTranslator,
              newTranslator);
          conflictingRegistrations.add(ptransformClass);
        }
      }
    }
    Set<Class<? extends PTransform>> conflictingRegistrationSet = conflictingRegistrations.build();

    if (!conflictingRegistrationSet.isEmpty()) {
      throw new IllegalArgumentException(
          String.format(
              "Conflicting registrations for: %s",
              Joiner.on(", ").join(conflictingRegistrationSet)));
    }

    return ImmutableMap.copyOf(translators);
  }

  /**
   * Translates a set of registered transforms whose content only differs based by differences in
   * their {@link FunctionSpec}s and URNs.
   */
  private static class KnownTransformPayloadTranslator<T extends PTransform<?, ?>>
      implements TransformTranslator<T> {

    @Override
    public boolean canTranslate(PTransform pTransform) {
      return getKnownPayloadTranslators().containsKey(pTransform.getClass());

View on GitHub (pinned to 12126d8942)