apache/beam · error · java.lang.RuntimeException

Could not find a matching method in transform for BuilderMe

Error message

Could not find a matching method in transform  for BuilderMethod. When using field names, make sure they are available in the compiled Java class.

What it means

After filtering the transform's methods by name match, parameter compatibility with the payload schema row, and PTransform return type, no method qualified. The service cannot resolve any builder method (or constructor path) matching the requested BuilderMethod in the given transform class.

Source

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

    return match;
  }

  private Method getMethod(
      PTransform<PInput, POutput> transform,
      BuilderMethod builderMethod,
      AllowedClass allowListClass) {

    Row builderMethodRow = decodeRow(builderMethod.getSchema(), builderMethod.getPayload());

    List<Method> matchingMethods =
        Arrays.stream(transform.getClass().getMethods())
            .filter(m -> isBuilderMethodForName(m, builderMethod.getName(), allowListClass))
            .filter(m -> parametersCompatible(m.getParameters(), builderMethodRow))
            .filter(m -> PTransform.class.isAssignableFrom(m.getReturnType()))
            .collect(Collectors.toList());

    if (matchingMethods.size() == 0) {
      throw new RuntimeException(
          "Could not find a matching method in transform "
              + transform
              + " for BuilderMethod"
              + builderMethod
              + ". When using field names, make sure they are available in the compiled"
              + " Java class.");
    } else if (matchingMethods.size() > 1) {
      throw new RuntimeException(
          "Expected to find exactly one matching method in transform "
              + transform
              + " for BuilderMethod"
              + builderMethod
              + " but found "
              + matchingMethods.size());
    }
    return matchingMethods.get(0);
  }

View on GitHub (pinned to 12126d8942)

Solutions

Correct the BuilderMethod name/field names in the expansion payload to match the transform's actual public builder methods.
Ensure parameter classes have a registered schema (@DefaultSchema / SchemaProvider) so their field names exist in the compiled class.
Align the transform artifact version used by the expansion service with the one the payload was generated from.
Simplify the payload to a single known builder method and add parameters incrementally to find the incompatible one.

Example fix

// before
payload: {name: "with_cout"}
// after
payload: {name: "withCount"}  // matches existing public builder method

Defensive patterns

Strategy: validation

Validate before calling

boolean resolvable(Class<?> transform, String methodName, Schema payload) {
  for (Method m : transform.getMethods()) {
    if (methodMatchesName(m, methodName) && parametersCompatible(m.getParameters(), payload)
        && PTransform.class.isAssignableFrom(m.getReturnType())) return true;
  }
  return false;
}

Try / catch

try {
  return getTransform(payload);
} catch (RuntimeException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Could not find a matching method")) {
    throw new InvalidExpansionRequest("No builder method on " + transformClass + " matches " + payload.getName(), e);
  }
  throw e;
}

Prevention

Generate payloads from the same (pinned) transform artifact version used by the expansion service.
Ensure every parameter POJO has schema field registration (@DefaultSchema) so field names exist in the compiled class.
Lint pipeline payloads against the transform's public builder method list in CI.
Avoid relying on the withX field-name convention when exact names are available.

When it happens

Trigger: Expansion payload references a builder method/field name that does not exist on the transform; payload field names not present in the compiled schema of the parameter class (stale compiled class without schema field registration); parameter types incompatible with the supplied row.

Common situations: Typos in the method/field name in the payload; transform rebuilt without @DefaultSchema registration so field names are missing from the compiled class; pipeline written against a newer/older transform version than deployed.

Related errors

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