apache/beam · error · IllegalArgumentException

Method [%s] has multiple definitions %s with different retur

Error message

Method [%s] has multiple definitions %s with different return types for [%s].

What it means

Thrown when a single PipelineOptions interface hierarchy defines the same bean method (same getter name) multiple times with different return types. Beam cannot resolve which type the property has, so registration fails.

Source

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

  private static void validateInheritedInterfacesExtendPipelineOptions(Class<?> klass) {
    Set<Class<?>> nonPipelineOptionsClasses = new LinkedHashSet<>();
    checkInheritedFrom(klass, PipelineOptions.class, nonPipelineOptionsClasses);

    if (!nonPipelineOptionsClasses.isEmpty()) {
      throwNonPipelineOptions(klass, nonPipelineOptionsClasses);
    }
  }

  private static class MultipleDefinitions {
    private Method method;
    private SortedSet<Method> collidingMethods;
  }

  private static void throwForMultipleDefinitions(
      Class<? extends PipelineOptions> iface, List<MultipleDefinitions> definitions) {
    if (definitions.size() == 1) {
      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());
    }

View on GitHub (pinned to 12126d8942)

Solutions

Align the return types of the colliding methods listed in the message so they are identical.
Or rename one of the properties (e.g. getFooMillis vs getFooDuration) to make them distinct.
Remove the duplicate definition if one interface should simply inherit the other's getter.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

java.util.Map<String, Class<?>> types = new java.util.HashMap<>();
for (java.lang.reflect.Method m : MyOptions.class.getMethods()) {
  Class<?> prev = types.putIfAbsent(m.getName(), m.getReturnType());
  if (prev != null && !prev.equals(m.getReturnType())) {
    throw new IllegalStateException(m.getName() + " has conflicting return types " + prev + " vs " + m.getReturnType());
  }
}

Try / catch

try {
  PipelineOptionsFactory.fromArgs(args).as(MyOptions.class);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("multiple definitions")) { /* unify return types or rename properties */ }
  throw e;
}

Prevention

Give each property a unique name across the entire options hierarchy
Avoid combining option interfaces that were developed independently without a name-collision review
Run a unit test calling .as() on every options interface in CI

When it happens

Trigger: PipelineOptionsFactory.fromArgs(...).as(iface.class) where throwForMultipleDefinitions receives a MultipleDefinitions entry: getFoo() returns String in one interface and int (or List<String>) in another inherited interface.

Common situations: Two teams define the same property name with different types in separate option interfaces that are later combined; renaming a property's type in one interface but not another; Java generics erasure hiding a conflicting return type.

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