apache/beam · error · RuntimeException

Method %s should not have return type StaticValueProvider, u

Error message

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

What it means

Same rule as RuntimeValueProvider: PipelineOptions getters must return the ValueProvider interface. ProxyInvocationHandler.getDefault rejects getters declared with the concrete StaticValueProvider type, because StaticValueProvider is an internal implementation that users should not expose in their options interface.

Source

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

   * "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;
      }
    }
    if (method.getReturnType().equals(ValueProvider.class)) {
      String propertyName = computedProperties.gettersToPropertyNames.get(method.getName());
      return defaultObject == null
          ? new RuntimeValueProvider(
              method.getName(),
              propertyName,

View on GitHub (pinned to 12126d8942)

Solutions

Change the getter's return type to ValueProvider<T>.
If the value is truly static, just declare a plain type or @Default-annotated ValueProvider getter.
Keep StaticValueProvider usage confined to pipeline construction code (StaticValueProvider.of(...)), not the options interface.

Example fix

// before
interface MyOptions extends PipelineOptions {
  StaticValueProvider<Integer> getLimit();
}
// after
interface MyOptions extends PipelineOptions {
  @Default.Integer(100)
  ValueProvider<Integer> getLimit();
}

Defensive patterns

Strategy: validation

Validate before calling

for (Method m : MyOptions.class.getMethods()) {
  if (m.getReturnType() == StaticValueProvider.class) {
    throw new IllegalArgumentException(m.getName() + " must return ValueProvider");
  }
}

Type guard

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

Prevention

Declare ValueProvider<T> in options interfaces.
Construct StaticValueProvider.of(...) only in pipeline code, not interface declarations.
Let @Default annotations supply static defaults.

When it happens

Trigger: Declaring a custom PipelineOptions getter with return type `StaticValueProvider<T>` (e.g., `StaticValueProvider<String> getFoo();`); thrown when getDefault computes the default during proxy invocation (called via value()).

Common situations: Auto-complete picking StaticValueProvider instead of ValueProvider; copying a DoFn that holds a StaticValueProvider field into the options interface; confusing the provider you construct in code with the type you declare in the interface.

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