apache/beam · error · UnsupportedOperationException

WatermarkHoldState is unsupported by the Fn API.

Error message

WatermarkHoldState is unsupported by the Fn API.

What it means

bindWatermark in FnApiStateAccessor is explicitly unimplemented in the Fn API: watermark hold state cannot be represented by the portability framework yet (tracked by BEAM-2535). Any user state or transform that requires a watermark hold binding throws UnsupportedOperationException immediately.

Solutions

1. Remove or replace WatermarkHoldState usage with supported state types (bag, multimap, orderedList) or event-time timers.
2. Run the pipeline on a non-portable runner path that supports watermark holds.
3. Track BEAM-2535 / upgrade Beam until Fn API watermark hold support lands.
4. Refactor to compute per-window results with timers instead of holding watermark output.

Example fix

// before
@StateId("hold") private final StateSpec<WatermarkHoldState> hold = StateSpecs.watermarkHold();
// after
@TimerId("cleanup") private final TimerSpec cleanup = TimerSpecs.timer(TimeDomain.EVENT_TIME);

// check pipeline for watermark holds before portable submission
if (pipelineContainsState(WatermarkHoldState.class)) {
  throw new IllegalArgumentException("WatermarkHoldState is not supported on Fn API runners");
}

When it happens

Trigger: A DoFn or composite transform calls state binding for WatermarkHoldState (e.g. via StateSpec<WatermarkHoldState> or bindWatermark) while running under the Fn API / portability harness.

Common situations: Porting a classic (non-portable) pipeline using watermark holds to Dataflow Runner v2 / Flink portable / other Fn API runners; libraries built on watermark-hold state executed in portable mode.

Related errors

• A cannot be expanded
• Attempting to add message
• Cannot access state in non-window observing context.
• environment with urn unimplemented
• error decoding append bag user state window key

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

Appendix: source

Thrown at sdks/java/harness/src/main/java/org/apache/beam/fn/harness/state/FnApiStateAccessor.java:1081

                            return get(view, currentWindowSupplier.get());
                          }

                          @Override
                          public BoundedWindow window() {
                            return currentWindowSupplier.get();
                          }
                        })));
  }

  /**
   * @deprecated The Fn API has no plans to implement WatermarkHoldState as of this writing and is
   *     waiting on resolution of BEAM-2535.
   */
  @Override
  @Deprecated
  public WatermarkHoldState bindWatermark(
      String id, StateSpec<WatermarkHoldState> spec, TimestampCombiner timestampCombiner) {
    throw new UnsupportedOperationException("WatermarkHoldState is unsupported by the Fn API.");
  }

  private static class UserStateCacheTokenKey implements Weighted {
    private final ByteString bytes;
    private final int hash;

    public UserStateCacheTokenKey(ByteString bytes) {
      this.bytes = bytes;
      this.hash = Objects.hash(UserStateCacheTokenKey.class, bytes);
    }

    @Override
    public boolean equals(Object o) {
      if (!(o instanceof UserStateCacheTokenKey)) {
        return false;
      }
      UserStateCacheTokenKey other = (UserStateCacheTokenKey) o;
      return hash == other.hash && bytes.equals(other.bytes);

View on GitHub (pinned to 12126d8942)