apache/beam · error · IllegalArgumentException

All inherited interfaces of [%s] should inherit from the Pip

Error message

All inherited interfaces of [%s] should inherit from the PipelineOptions interface. The following inherited interfaces do not:%n - %s

What it means

Thrown when a PipelineOptions interface (or any interface it extends, transitively) inherits from interfaces that do not extend PipelineOptions. Beam requires the whole interface hierarchy to descend from PipelineOptions so it can enumerate properties and build the proxy implementation.

Source

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

    for (Class<?> klass : checkClass.getInterfaces()) {
      checkInheritedFrom(klass, fromClass, nonPipelineOptions);
    }
  }

  private static void throwNonPipelineOptions(
      Class<?> klass, Set<Class<?>> nonPipelineOptionsClasses) {
    StringBuilder errorBuilder =
        new StringBuilder(
            String.format(
                "All inherited interfaces of [%s] should inherit from the PipelineOptions"
                    + " interface. The following inherited interfaces do not:",
                klass.getName()));

    for (Class<?> invalidKlass : nonPipelineOptionsClasses) {
      errorBuilder.append(String.format("%n - %s", invalidKlass.getName()));
    }
    throw new IllegalArgumentException(errorBuilder.toString());
  }

  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) {

View on GitHub (pinned to 12126d8942)

Solutions

Make the offending interface listed in the message extend PipelineOptions.
Or stop extending it and duplicate/move the needed getters directly into the options interface.
Keep every interface in the options hierarchy rooted at PipelineOptions going forward.

Example fix

// before
interface Common {
  String getFoo();
}
interface MyOptions extends PipelineOptions, Common {}
// after
interface Common extends PipelineOptions {
  String getFoo();
}
interface MyOptions extends PipelineOptions, Common {}

Defensive patterns

Strategy: validation

Validate before calling

static void assertAllExtend(Class<?> klass) {
  for (Class<?> i : klass.getInterfaces()) {
    if (!PipelineOptions.class.isAssignableFrom(i)) {
      throw new IllegalStateException(i.getName() + " must extend PipelineOptions");
    }
    assertAllExtend(i);
  }
}

Type guard

static boolean isPipelineOptionsHierarchy(Class<?> k) {
  return PipelineOptions.class.isAssignableFrom(k);
}

Try / catch

try {
  PipelineOptionsFactory.fromArgs(args).as(MyOptions.class);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("should inherit from the PipelineOptions")) { /* fix interface hierarchy */ }
  throw e;
}

Prevention

Always declare shared option interfaces as 'interface X extends PipelineOptions'
Never reuse plain DTO interfaces as options parents
Review 'extends' clauses when extracting common getters into a base interface

When it happens

Trigger: PipelineOptionsFactory.fromArgs(...).as(Klass.class) or .create() where validateInheritedInterfacesExtendPipelineOptions finds nonPipelineOptionsClasses: Klass extends a plain (non-PipelineOptions) Java interface.

Common situations: Extracting shared getters into a common utility interface and extending it without adding 'extends PipelineOptions'; reusing a DTO interface as an options interface; refactoring where the base interface's extends clause was dropped.

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