apache/beam · error · RuntimeException

Method %s should not have return type RuntimeValueProvider,

Error message

Method %s should not have return type RuntimeValueProvider, use ValueProvider instead.

What it means

PipelineOptions getter methods must declare the interface ValueProvider, not concrete implementations. ProxyInvocationHandler.getDefault rejects getters whose return type is exactly RuntimeValueProvider, since RuntimeValueProvider is an internal runtime type that users should never reference directly.

Source

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

      throw new RuntimeException("Unable to parse representation", e);
    }
  }

  /**
   * Returns a default value for the method based upon {@code @Default} metadata on the getter to
   * return values. If there is no {@code @Default} annotation on the getter, then a <a href=
   * "https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html">default</a> as per
   * the Java Language Specification for the expected return type is returned.
   *
   * @param proxy The proxy object for which we are attempting to get the default.
   * @param method The getter method that was invoked.
   * @return The default value from an {@link Default} annotation if present, otherwise a default
   *     value as per the Java Language Specification.
   */
  @SuppressWarnings({"unchecked", "rawtypes"})
  private Object getDefault(PipelineOptions proxy, Method method) {
    if (method.getReturnType().equals(RuntimeValueProvider.class)) {
      throw new RuntimeException(
          String.format(
              "Method %s should not have return type "
                  + "RuntimeValueProvider, use ValueProvider instead.",
              method.getName()));
    }
    if (method.getReturnType().equals(StaticValueProvider.class)) {
      throw new RuntimeException(
          String.format(
              "Method %s should not have return type "
                  + "StaticValueProvider, use ValueProvider instead.",
              method.getName()));
    }
    @Nullable Object defaultObject = null;
    for (Annotation annotation : method.getAnnotations()) {
      defaultObject = returnDefaultHelper(annotation, proxy, method);
      if (defaultObject != null) {
        break;
      }

View on GitHub (pinned to 12126d8942)

Solutions

Change the getter's return type to ValueProvider<T>.
Rebuild/re-run; the runtime will return a RuntimeValueProvider behind the ValueProvider interface automatically.
Never reference RuntimeValueProvider or StaticValueProvider in PipelineOptions interface definitions.

Example fix

// before
interface MyOptions extends PipelineOptions {
  RuntimeValueProvider<String> getInput();
}
// after
interface MyOptions extends PipelineOptions {
  @Default.String("in")
  ValueProvider<String> getInput();
}

Defensive patterns

Strategy: validation

Validate before calling

// Fail fast at startup: scan custom options interfaces
for (Method m : MyOptions.class.getMethods()) {
  if (m.getReturnType() == RuntimeValueProvider.class) {
    throw new IllegalArgumentException(m.getName() + " must return ValueProvider");
  }
}

Type guard

static boolean usesConcreteValueProvider(Class<? extends PipelineOptions> opts) {
  return java.util.Arrays.stream(opts.getMethods())
      .anyMatch(m -> m.getReturnType() == RuntimeValueProvider.class);
}

Prevention

Always declare ValueProvider<T> in options interfaces, never concrete implementations.
Never import RuntimeValueProvider/StaticValueProvider into options interface files.
Use @Default annotations with ValueProvider getters for defaults.

When it happens

Trigger: Declaring a custom PipelineOptions interface with a getter like `RuntimeValueProvider<String> getFoo();` — detected when the default value is computed during proxy method invocation (called via ValueProvider.value() resolution).

Common situations: Copy-pasting from internal Beam code when defining custom options; IDE auto-completing to RuntimeValueProvider; misunderstanding that RuntimeValueProvider is the runtime implementation rather than the interface to declare.

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/f6b274819f7d0034. Report an issue: GitHub.