apache/beam · error · IllegalArgumentException

label + ": " + String.format(message, args)

Error message

label + ": " + String.format(message, args)

What it means

DoFnSignatures builds IllegalArgumentException messages for invalid DoFn signatures via a @FormatMethod helper that prefixes them with the DoFn class label. The thrown message is 'label: <formatted message>' describing a bad parameter, e.g. an unsupported parameter type at a given index. Beam throws this at pipeline-construction time when a DoFn method signature violates the DoFn processing-method rules.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/reflect/DoFnSignatures.java:2502

    }

    ErrorReporter forMethod(Class<? extends Annotation> annotation, Method method) {
      return new ErrorReporter(
          this,
          String.format(
              "@%s %s", format(annotation), (method == null) ? "(absent)" : format(method)));
    }

    ErrorReporter forParameter(ParameterDescription param) {
      return new ErrorReporter(
          this,
          String.format(
              "parameter of type %s at index %s", format(param.getType()), param.getIndex()));
    }

    @FormatMethod
    void throwIllegalArgument(@FormatString String message, Object... args) {
      throw new IllegalArgumentException(label + ": " + String.format(message, args));
    }

    @FormatMethod
    public void checkArgument(boolean condition, @FormatString String message, Object... args) {
      if (!condition) {
        throwIllegalArgument(message, args);
      }
    }

    @FormatMethod
    public void checkNotNull(Object value, @FormatString String message, Object... args) {
      if (value == null) {
        throwIllegalArgument(message, args);
      }
    }
  }

  public static StateSpec<?> getStateSpecOrThrow(

View on GitHub (pinned to 12126d8942)

Solutions

1. Fix the DoFn method signature so parameters follow the allowed order/types: (ProcessContext, BoundedWindow, RestrictionT, WatermarkEstimatorT, ...)
2. Read the full message: it names the offending type and its parameter index; correct that exact parameter
3. Use @ProcessElement with 'OutputReceiver<OutputT>' (or ProcessContext) rather than custom receiver types
4. Check the Beam version's DoFnSignatures javadoc for the accepted parameter kinds

Example fix

// before
class MyFn extends DoFn<String, String> {
  @ProcessElement
  public void process(BoundedWindow window, ProcessContext ctx) { ... }
}

// after
class MyFn extends DoFn<String, String> {
  @ProcessElement
  public void process(ProcessContext ctx, BoundedWindow window) { ... }
}

// Validate DoFn method params before submitting the pipeline
List<Class<?>> allowed = List.of(DoFn.ProcessContext.class, DoFn.OutputReceiver.class,
    BoundedWindow.class, RestrictionTracker.class, WatermarkEstimator.class);
for (Method m : myFn.getClass().getDeclaredMethods()) {
  if (m.isAnnotationPresent(DoFn.ProcessElement.class)) {
    for (Class<?> p : m.getParameterTypes()) {
      if (!allowed.stream().anyMatch(a -> a.isAssignableFrom(p))) {
        throw new IllegalArgumentException("Unsupported DoFn parameter type: " + p);
      }
    }
  }
}

static boolean isValidDoFnParam(Class<?> p) {
  return DoFn.ProcessContext.class.isAssignableFrom(p)
      || BoundedWindow.class.isAssignableFrom(p)
      || DoFn.OutputReceiver.class.isAssignableFrom(p);
}

When it happens

Trigger: Declaring a @ProcessElement (or @StartBundle/@FinishBundle) method whose parameter at some index has a type Beam cannot recognize (e.g. wrong order of ProcessContext, BoundedWindow, extra types), so signature analysis calls throwIllegalArgument with 'parameter of type %s at index %s'.

Common situations: Migrating DoFns across Beam versions where the allowed parameter list changed; hand-written DoFns with parameters in the wrong order (ProcessContext must come first, BoundedWindow before restrictions); typos in types like using a custom context class instead of DoFn.ProcessContext.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• ApproximateUnique.PerKey needs an estimation error between 1
• timerFrequency must be greater than zero
• Expected to have found at most one parameter of type %s but
• lenientFormat(errorMessageTemplate, p1, p2)
• must either have a non-empty list of PCollections, or must f

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