{"record":{"id":"917a1d55014f8757","repo":"apache/beam","slug":"watermarkholdstate-is-unsupported-by-the-fn-api","errorCode":null,"errorMessage":"WatermarkHoldState is unsupported by the Fn API.","messagePattern":"WatermarkHoldState is unsupported by the Fn API\\.","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"sdks/java/harness/src/main/java/org/apache/beam/fn/harness/state/FnApiStateAccessor.java","lineNumber":1081,"sourceCode":"                            return get(view, currentWindowSupplier.get());\n                          }\n\n                          @Override\n                          public BoundedWindow window() {\n                            return currentWindowSupplier.get();\n                          }\n                        })));\n  }\n\n  /**\n   * @deprecated The Fn API has no plans to implement WatermarkHoldState as of this writing and is\n   *     waiting on resolution of BEAM-2535.\n   */\n  @Override\n  @Deprecated\n  public WatermarkHoldState bindWatermark(\n      String id, StateSpec<WatermarkHoldState> spec, TimestampCombiner timestampCombiner) {\n    throw new UnsupportedOperationException(\"WatermarkHoldState is unsupported by the Fn API.\");\n  }\n\n  private static class UserStateCacheTokenKey implements Weighted {\n    private final ByteString bytes;\n    private final int hash;\n\n    public UserStateCacheTokenKey(ByteString bytes) {\n      this.bytes = bytes;\n      this.hash = Objects.hash(UserStateCacheTokenKey.class, bytes);\n    }\n\n    @Override\n    public boolean equals(Object o) {\n      if (!(o instanceof UserStateCacheTokenKey)) {\n        return false;\n      }\n      UserStateCacheTokenKey other = (UserStateCacheTokenKey) o;\n      return hash == other.hash && bytes.equals(other.bytes);","sourceCodeStart":1063,"sourceCodeEnd":1099,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/harness/src/main/java/org/apache/beam/fn/harness/state/FnApiStateAccessor.java#L1063-L1099","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove or replace WatermarkHoldState usage with supported state types (bag, multimap, orderedList) or event-time timers.","Run the pipeline on a non-portable runner path that supports watermark holds.","Track BEAM-2535 / upgrade Beam until Fn API watermark hold support lands.","Refactor to compute per-window results with timers instead of holding watermark output."],"exampleFix":"// before\n@StateId(\"hold\") private final StateSpec<WatermarkHoldState> hold = StateSpecs.watermarkHold();\n// after\n@TimerId(\"cleanup\") private final TimerSpec cleanup = TimerSpecs.timer(TimeDomain.EVENT_TIME);","handlingStrategy":"validation","validationCode":"// check pipeline for watermark holds before portable submission\nif (pipelineContainsState(WatermarkHoldState.class)) {\n  throw new IllegalArgumentException(\"WatermarkHoldState is not supported on Fn API runners\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Avoid WatermarkHoldState in pipelines targeting portable runners","Refactor to event-time timers or ordered list state","Track BEAM-2535 for support status"],"tags":["state","unsupported","beam","portability"],"backgroundTag":"method-not-implemented","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}