apache/beam · error · java.lang.IllegalArgumentException

Could not invoke the builder method on transform with…

Error message

Could not invoke the builder method  on transform  with parameter schema

What it means

The transform class was instantiated, but invoking the selected builder method reflectively failed with IllegalAccessException or InvocationTargetException. The service wraps this in IllegalArgumentException, naming the builder method, the transform, and the schema of the parameters.

Solutions

Read the InvocationTargetException's cause ('Caused by') and fix the invalid input that made the builder throw.
Make the transform class and the builder method public so reflection can invoke them.
Verify the parameter schema in the expansion request matches what the builder method expects for the deployed version.
Rebuild/redeploy the expansion service with the same transform version your pipeline payload targets.

Example fix

// before
// package-private builder throwing on bad value
MyTransform withCount(int n) { if (n < 0) throw new IllegalArgumentException(); ... }
// after
public MyTransform withCount(int n) { /* accept validated n */ ... }

Defensive patterns

Strategy: try-catch

Validate before calling

// validate builder inputs against the method schema before expansion
Method m = resolveBuilderMethod(transformClass, builderName);
for (Parameter p : m.getParameters()) {
  if (!schemaCompatible(p, builderMethodRow)) throw new IllegalArgumentException("Bad value for " + p.getName());
}

Type guard

function builderAccessible(transform) {
  return java.lang.reflect.Modifier.isPublic(transform.getClass().getModifiers());
}

Try / catch

try {
  return applyBuilderMethods(transform, method, row);
} catch (IllegalArgumentException e) {
  Throwable cause = e.getCause();
  if (cause instanceof InvocationTargetException) {
    log.error("Builder {} threw: {}", method, cause.getCause(), cause); // fix the invalid input reported by the builder
  }
  throw e;
}

Prevention

Keep builder methods simple validators/setters; defer heavy work to expand(), not the builder.
Make transform classes and builder methods public.
Test each builder method locally with representative payload rows before exposing via expansion.
Keep payload parameter schema in sync with the deployed transform version.

When it happens

Trigger: Calling ExpansionService expand where the resolved builder method (e.g. a 'withX' method or @MultiLanguageBuilderMethod) throws an exception during invocation, or is not accessible from the expansion service (non-public class/method).

Common situations: Builder method validates its arguments and throws (bad values supplied via the schema payload); method lives in a package-private class; version skew between payload schema and deployed transform so an internal call fails.

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

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

Appendix: source

Thrown at sdks/java/expansion-service/src/main/java/org/apache/beam/sdk/expansion/service/JavaClassLookupTransformProvider.java:159

  @SuppressWarnings("assignment")
  private PTransform<PInput, POutput> applyBuilderMethods(
      PTransform<PInput, POutput> transform,
      JavaClassLookupPayload payload,
      AllowedClass allowListClass) {
    for (BuilderMethod builderMethod : payload.getBuilderMethodsList()) {
      Method method = getMethod(transform, builderMethod, allowListClass);
      try {
        Row builderMethodRow = decodeRow(builderMethod.getSchema(), builderMethod.getPayload());
        transform =
            (PTransform<PInput, POutput>)
                method.invoke(
                    transform,
                    getParameterValues(
                        method.getParameters(),
                        builderMethodRow,
                        method.getGenericParameterTypes()));
      } catch (IllegalAccessException | InvocationTargetException e) {
        throw new IllegalArgumentException(
            "Could not invoke the builder method "
                + builderMethod
                + " on transform "
                + transform
                + " with parameter schema "
                + builderMethod.getSchema(),
            e);
      }
    }

    return transform;
  }

  private boolean isBuilderMethodForName(
      Method method, String nameFromPayload, AllowedClass allowListClass) {
    // Lookup based on method annotations
    for (Annotation annotation : method.getAnnotations()) {
      if (annotation instanceof MultiLanguageBuilderMethod) {

View on GitHub (pinned to 12126d8942)