apache/beam · error · IllegalStateException

Failed to locate required method ${className}.${methodName}

Error message

Failed to locate required method ${className}.${methodName}

What it means

The generated ByteBuddy invoker calls helper methods on DoFnInvoker.ArgumentProvider (pipeline options, state/timer accessors). This IllegalStateException is thrown when a required method cannot be located reflectively, meaning the ArgumentProvider class loaded at runtime does not match what the generated code expects.

Source

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

        if (!paramT.isPrimitive()) {
          pushParameters.add(TypeCasting.to(paramT));
        }
      }
      return new StackManipulation.Compound(pushParameters);
    }
  }

  /**
   * This wrapper exists to convert checked exceptions to unchecked exceptions, since if this fails
   * the library itself is malformed.
   */
  private static MethodDescription getExtraContextFactoryMethodDescription(
      String methodName, Class<?>... parameterTypes) {
    try {
      return new MethodDescription.ForLoadedMethod(
          DoFnInvoker.ArgumentProvider.class.getMethod(methodName, parameterTypes));
    } catch (Exception e) {
      throw new IllegalStateException(
          String.format(
              "Failed to locate required method %s.%s",
              DoFnInvoker.ArgumentProvider.class.getSimpleName(), methodName),
          e);
    }
  }

  /**
   * Calls a zero-parameter getter on the {@link DoFnInvoker.ArgumentProvider}, which must be on top
   * of the stack.
   */
  private static StackManipulation simpleExtraContextParameter(String methodName) {
    return new StackManipulation.Compound(
        MethodInvocation.invoke(getExtraContextFactoryMethodDescription(methodName)));
  }

  static StackManipulation getExtraContextParameter(
      DoFnSignature.Parameter parameter, final StackManipulation pushDelegate) {

View on GitHub (pinned to 12126d8942)

Solutions

1. Ensure a single consistent beam-sdks-java-core version on the classpath (mvn dependency:tree; exclude transitive duplicates).
2. Rebuild the jar so generated code matches the runtime SDK's ArgumentProvider API.
3. If shading, relocate the whole org.apache.beam tree consistently or leave the reflect package untouched.

Example fix

// before
<dependency>beam-sdks-java-core 2.30.0</dependency> <!-- transitive 2.50.0 also present -->
// after
mvn dependency:tree -Dincludes=org.apache.beam
<!-- pin all beam artifacts to one version and add exclusions for stale copies -->

Class<?> ap = DoFnInvoker.ArgumentProvider.class;
Method m;
try {
  m = ap.getMethod("getPipelineOptions");
} catch (NoSuchMethodException e) {
  throw new IllegalStateException("Wrong beam-sdks-java-core version on classpath", e);
}

When it happens

Trigger: getExtraContextFactoryMethodDescription is asked for a method name/parameter types that do not exist on the loaded DoFnInvoker.ArgumentProvider class — typically a Beam SDK version mismatch on the classpath.

Common situations: Mixed beam-sdks-java-core versions in a fat/uber jar; shading or relocation that dropped/renamed ArgumentProvider methods; partial SDK upgrade.

Related errors

• Failed to locate ProcessContinuation.stop()
• Unable to bind invoker for ${fnClass}
• ${e.getMessage()}
• Failed to locate DefaultGetSize.validateSize()
• Unable to find UserCodeException.wrap

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