apache/beam · error · RuntimeException

Only a RuntimeValueProvider or a NestedValueProvider can…

Error message

Only a RuntimeValueProvider or a NestedValueProvider can supply a property name.

What it means

NestedValueProvider.propertyName() can only report the underlying property name when the wrapped value is itself a RuntimeValueProvider or another NestedValueProvider. A plain static/serializable value has no pipeline-option property backing it, so a RuntimeException is thrown.

Solutions

Only call propertyName() on providers created from PipelineOptions value-provider fields
Wrap the value in a runtime provider via options.valueProvider(...) instead of a static value
Guard with instanceof RuntimeValueProvider/NestedValueProvider before calling propertyName(), or catch RuntimeException

Example fix

// before
String name = myNestedProvider.propertyName(); // throws when backing value is static
// after
String name = provider instanceof RuntimeValueProvider || provider instanceof NestedValueProvider
    ? provider.propertyName() : null;

Defensive patterns

Strategy: type-guard

Validate before calling

if (!(provider instanceof RuntimeValueProvider) && !(provider instanceof NestedValueProvider)) { /* static value: no property name available */ }

Type guard

boolean hasPropertyName(ValueProvider<?> v) { return v instanceof RuntimeValueProvider || v instanceof NestedValueProvider; }

Try / catch

try { name = provider.propertyName(); } catch (RuntimeException e) { name = null; /* static value */ }

Prevention

Build NestedValueProviders only from option-backed providers
Avoid propertyName() introspection on literal/StaticValueProvider values
Document that propertyName() is only meaningful for runtime-derived providers

When it happens

Trigger: Calling propertyName() on a NestedValueProvider that wraps a static value (e.g. NestedValueProvider.of(StaticValueProvider.of(x), fn)) instead of one derived from a PipelineOptions ValueProvider field.

Common situations: Introspecting a value provider to learn which option it maps to, but the provider was constructed from a literal constant rather than from a PipelineOptions getter; common in connector/IO code paths that assume runtime options.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/options/ValueProvider.java:163

      if (cachedValue == null) {
        cachedValue = translator.apply(value.get());
      }
      return cachedValue;
    }

    @Override
    public boolean isAccessible() {
      return value.isAccessible();
    }

    /** Returns the property name associated with this provider. */
    public String propertyName() {
      if (value instanceof RuntimeValueProvider) {
        return ((RuntimeValueProvider) value).propertyName();
      } else if (value instanceof NestedValueProvider) {
        return ((NestedValueProvider) value).propertyName();
      } else {
        throw new RuntimeException(
            "Only a RuntimeValueProvider or a NestedValueProvider can supply"
                + " a property name.");
      }
    }

    @Override
    public String toString() {
      if (isAccessible()) {
        return String.valueOf(get());
      }
      return MoreObjects.toStringHelper(this)
          .add("value", value)
          .add("translator", translator.getClass().getSimpleName())
          .toString();
    }

    @Override
    public boolean equals(@Nullable Object other) {

View on GitHub (pinned to 12126d8942)