apache/beam · error · IllegalArgumentException

Property getters are inconsistently marked with @%s:

Error message

Property getters are inconsistently marked with @%s:

What it means

The aggregated variant of the inconsistent-getter-annotation error: when multiple properties have inconsistently applied annotations, Beam throws a single message 'Property getters are inconsistently marked with @%s:' listing each offending property line by line.

Source

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

              getter.descriptor.getName(),
              annotationClass.getSimpleName(),
              getter.getterClassNames,
              getter.gettersWithTheAnnotationClassNames));
    } else if (getters.size() > 1) {
      StringBuilder errorBuilder =
          new StringBuilder(
              String.format(
                  "Property getters are inconsistently marked with @%s:",
                  annotationClass.getSimpleName()));
      for (InconsistentlyAnnotatedGetters getter : getters) {
        errorBuilder.append(
            String.format(
                "%n  - Expected for property [%s] to be marked on all %s, " + "found only on %s",
                getter.descriptor.getName(),
                getter.getterClassNames,
                getter.gettersWithTheAnnotationClassNames));
      }
      throw new IllegalArgumentException(errorBuilder.toString());
    }
  }

  private static class AnnotatedSetter {
    PropertyDescriptor descriptor;
    Iterable<String> settersWithTheAnnotationClassNames;
  }

  private static void throwForSettersWithTheAnnotation(
      List<AnnotatedSetter> setters, Class<? extends Annotation> annotationClass) {
    if (setters.size() == 1) {
      AnnotatedSetter setter = setters.get(0);
      throw new IllegalArgumentException(
          String.format(
              "Expected setter for property [%s] to not be marked with @%s on %s",
              setter.descriptor.getName(),
              annotationClass.getSimpleName(),
              setter.settersWithTheAnnotationClassNames));

View on GitHub (pinned to 12126d8942)

Solutions

Fix each listed property so its annotation is present (or absent) on every declaration in the hierarchy.
Use an IDE 'find usages' on each getter name to locate all declarations.
Consider defining the annotated getter once in the most-derived interface and inheriting it.

Example fix

// before
interface A extends PipelineOptions { @Default.String("x") String getFoo(); String getBar(); }
interface B extends A { String getFoo(); @Default.Integer(1) int getBar(); }
// after
interface A extends PipelineOptions { @Default.String("x") String getFoo(); @Default.Integer(1) int getBar(); }
interface B extends A {}

Defensive patterns

Strategy: validation

Validate before calling

// Check annotation consistency for every getter across the hierarchy before registration:
java.util.Map<String, java.util.Set<Boolean>> marks = new java.util.HashMap<>();
for (java.lang.reflect.Method m : MyOptions.class.getMethods()) {
  if (m.getName().startsWith("get")) {
    marks.computeIfAbsent(m.getName(), k -> new java.util.HashSet<>())
         .add(m.getAnnotations().length > 0);
  }
}
marks.forEach((n, s) -> { if (s.size() > 1) System.err.println("inconsistent annotations on " + n); });

Try / catch

try {
  PipelineOptionsFactory.fromArgs(args).as(MyOptions.class);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("inconsistently marked with @")) { /* fix each listed property */ }
  throw e;
}

Prevention

Apply annotation changes to all overriding declarations in one commit
Use IDE 'find usages' before adding/removing an annotation on a getter
Validate options interfaces in a unit test at build time

When it happens

Trigger: PipelineOptionsFactory registration when throwForGettersWithInconsistentAnnotation receives getters.size() > 1; a builder appends one '%n - Expected for property [...] to be marked on all [...] found only on [...]' line per property before throwing.

Common situations: Bulk annotation passes (@Default, @Hidden) applied to some but not all overriding getters; code reviews missing inherited declarations of the same property.

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