apache/beam · error · IllegalArgumentException

Interface [%s] has Methods with multiple definitions with di

Error message

Interface [%s] has Methods with multiple definitions with different return types:

What it means

The multi-definition variant of the multiple-definitions error: when several properties on one interface have colliding definitions with different return types, Beam aggregates them into one message headed 'Interface [%s] has Methods with multiple definitions with different return types:'. It fails PipelineOptions registration the same way as the single case.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/options/PipelineOptionsFactory.java:1391

      MultipleDefinitions errDef = definitions.get(0);
      throw new IllegalArgumentException(
          String.format(
              "Method [%s] has multiple definitions %s with different return types for [%s].",
              errDef.method.getName(), errDef.collidingMethods, iface.getName()));
    } else if (definitions.size() > 1) {
      StringBuilder errorBuilder =
          new StringBuilder(
              String.format(
                  "Interface [%s] has Methods with multiple definitions with different return"
                      + " types:",
                  iface.getName()));
      for (MultipleDefinitions errDef : definitions) {
        errorBuilder.append(
            String.format(
                "%n  - Method [%s] has multiple definitions %s",
                errDef.method.getName(), errDef.collidingMethods));
      }
      throw new IllegalArgumentException(errorBuilder.toString());
    }
  }

  private static class InconsistentlyAnnotatedGetters {
    PropertyDescriptor descriptor;
    Iterable<String> getterClassNames;
    Iterable<String> gettersWithTheAnnotationClassNames;
  }

  private static void throwForGettersWithInconsistentAnnotation(
      List<InconsistentlyAnnotatedGetters> getters, Class<? extends Annotation> annotationClass) {
    if (getters.size() == 1) {
      InconsistentlyAnnotatedGetters getter = getters.get(0);
      throw new IllegalArgumentException(
          String.format(
              "Expected getter for property [%s] to be marked with @%s on all %s, "
                  + "found only on %s",
              getter.descriptor.getName(),

View on GitHub (pinned to 12126d8942)

Solutions

Read each listed '- Method [...] has multiple definitions' line to identify all colliding properties.
Fix every listed method: unify return types across the hierarchy or rename the properties.
Re-run the pipeline; repeat until no collisions remain since all are reported together.

Example fix

// before
interface A extends PipelineOptions { String getFoo(); int getBar(); }
interface B extends PipelineOptions { int getFoo(); long getBar(); }
// after
interface A extends PipelineOptions { String getFoo(); int getBar(); }
interface B extends PipelineOptions { String getFoo(); int getBar(); }

Defensive patterns

Strategy: validation

Validate before calling

// Same check as error 242; run it before registration to enumerate all collisions:
java.util.Map<String, java.util.Set<Class<?>>> byName = new java.util.HashMap<>();
for (java.lang.reflect.Method m : MyOptions.class.getMethods()) {
  byName.computeIfAbsent(m.getName(), k -> new java.util.HashSet<>()).add(m.getReturnType());
}
byName.forEach((name, rets) -> { if (rets.size() > 1) System.err.println("collision: " + name + " -> " + rets); });

Try / catch

try {
  PipelineOptionsFactory.fromArgs(args).as(MyOptions.class);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("multiple definitions with different return types:")) { /* fix each listed method */ }
  throw e;
}

Prevention

Parse every '- Method [...] has multiple definitions' line and fix all at once
Keep property naming conventions unique per feature interface
Add an integration test that instantiates the full combined options class

When it happens

Trigger: PipelineOptionsFactory.fromArgs(...).as(iface.class) where throwForMultipleDefinitions receives definitions.size() > 1; the body appends one line per colliding method before throwing.

Common situations: Merging several option interfaces (e.g. combined pipeline options inheriting from many feature-specific interfaces) where multiple properties clash at once; large refactors that rename types incompletely.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

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