apache/beam · error · RuntimeException

Unknown method [ ] invoked with args [ ].

Error message

Unknown method [<method>] invoked with args [<args>].

What it means

ProxyInvocationHandler.invoke received a Method it does not handle — neither a getter/setter of a known option nor a supported special method (e.g., as, populateDisplayData paths it understands). It throws a RuntimeException naming the method and args. This indicates the proxy was called with a method outside its known surface.

Solutions

  1. Only invoke declared option getter/setter methods or supported helper methods (as(), cloneAs(), etc.) on the proxy
  2. Regenerate/refresh the options instance after classloader changes instead of reusing a stale proxy
  3. Fix the test/reflective call to target a real option method

Example fix

// before
Method m = opts.getClass().getMethod("nonExistentMethod");
m.invoke(opts);
// after
opts.setJobName("my-job"); // use a real declared option method
Defensive patterns

Strategy: try-catch

Validate before calling

Method m = MyOptions.class.getMethod(name); // fails early if not a real option method
if (!PropertyNames.isOptionMethod(m)) throw new IllegalArgumentException(name + " is not an option");

Try / catch

try { m.invoke(proxy, args); } catch (RuntimeException e) { if (e.getMessage().startsWith("Unknown method")) { /* use correct option API */ } }

Prevention

When it happens

Trigger: Calling a method on a PipelineOptions proxy object that isn't a declared option property or supported handler method, e.g. an interface added method invoked reflectively, or a test invoking an unknown Method.

Common situations: Default/static interface methods invoked via raw reflection on the proxy; mixing proxies/options instances across classloaders (Beam classloader changes) so computed method maps don't match; unit tests probing unknown methods.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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

Appendix: source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/options/ProxyInvocationHandler.java:244

        // Lazy bind the default to the method.
        Object value =
            jsonOptions.containsKey(propertyName)
                ? getValueFromJson(propertyName, method)
                : getDefault((PipelineOptions) proxy, method);
        options.put(propertyName, BoundValue.fromDefault(value));
      }
      return options.get(propertyName).getValue();
    } else if (properties.settersToPropertyNames.containsKey(methodName)) {
      BoundValue prev =
          options.put(
              properties.settersToPropertyNames.get(methodName),
              BoundValue.fromExplicitOption(args[0]));
      if (prev == null ? args[0] != null : !Objects.equals(args[0], prev.getValue())) {
        revision.incrementAndGet();
      }
      return Void.TYPE;
    }
    throw new RuntimeException(
        "Unknown method [" + method + "] invoked with args [" + Arrays.toString(args) + "].");
  }

  public String getOptionName(Method method) {
    return computedProperties.gettersToPropertyNames.get(method.getName());
  }

  private void writeObject(java.io.ObjectOutputStream stream) throws IOException {
    throw new NotSerializableException(
        "PipelineOptions objects are not serializable and should not be embedded into transforms "
            + "(did you capture a PipelineOptions object in a field or in an anonymous class?). "
            + "Instead, if you're using a DoFn, access PipelineOptions at runtime "
            + "via ProcessContext/StartBundleContext/FinishBundleContext.getPipelineOptions(), "
            + "or pre-extract necessary fields from PipelineOptions "
            + "at pipeline construction time.");
  }

  /** Track whether options values are explicitly set, or retrieved from defaults. */

View on GitHub (pinned to 12126d8942)