apache/beam · warning · UnsupportedOperationException

Unknown window function ${simpleName}

Error message

Unknown window function ${simpleName}

What it means

When explaining a BeamAggregationRel plan, the explain string includes window-function parameters. Only FixedWindows, SlidingWindows and Sessions are recognized; any other WindowFn (e.g. CalendarWindows or a custom one) is unknown to this code and throws UnsupportedOperationException during EXPLAIN/plan rendering.

Source

Thrown at sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/rel/BeamAggregationRel.java:177

      String window = windowFn.getClass().getSimpleName() + "($" + String.valueOf(windowFieldIndex);
      if (windowFn instanceof FixedWindows) {
        FixedWindows fn = (FixedWindows) windowFn;
        window = window + ", " + fn.getSize().toString() + ", " + fn.getOffset().toString();
      } else if (windowFn instanceof SlidingWindows) {
        SlidingWindows fn = (SlidingWindows) windowFn;
        window =
            window
                + ", "
                + fn.getPeriod().toString()
                + ", "
                + fn.getSize().toString()
                + ", "
                + fn.getOffset().toString();
      } else if (windowFn instanceof Sessions) {
        Sessions fn = (Sessions) windowFn;
        window = window + ", " + fn.getGapDuration().toString();
      } else {
        throw new UnsupportedOperationException(
            "Unknown window function " + windowFn.getClass().getSimpleName());
      }
      window = window + ")";
      pw.item("window", window);
    }
    return pw;
  }

  @Override
  public PTransform<PCollectionList<Row>, PCollection<Row>> buildPTransform() {
    Schema outputSchema = CalciteUtils.toSchema(getRowType());
    List<FieldAggregation> aggregationAdapters =
        getNamedAggCalls().stream()
            .map(aggCall -> new FieldAggregation(aggCall.getKey(), aggCall.getValue()))
            .collect(toList());

    return new Transform(
        windowFn, windowFieldIndex, getGroupSet(), aggregationAdapters, outputSchema);

View on GitHub (pinned to 12126d8942)

Solutions

1. Use TUMBLE/HOP/SESSION windowing in the SQL query so the rel uses a supported WindowFn
2. Convert the input PCollection to a supported windowing (fixed/sliding/session) before the SQL aggregation
3. Catch UnsupportedOperationException around explain/plan-printing if you must explain pipelines with custom windows
4. Extend BeamAggregationRel.explainTerms to describe your WindowFn if forking

Example fix

// before
SELECT COUNT(*) FROM t -- input uses CalendarWindows
// after
SELECT COUNT(*) FROM t GROUP BY TUMBLE(ts, INTERVAL '1' DAY)

import org.apache.beam.sdk.transforms.windowing.*;
WindowFn<?, ?> fn = upstream.getWindowingStrategy().getWindowFn();
boolean explainable = fn instanceof FixedWindows || fn instanceof SlidingWindows || fn instanceof Sessions;

boolean hasExplainableWindowFn(PCollection<?> pc) {
  WindowFn<?, ?> fn = pc.getWindowingStrategy().getWindowFn();
  return fn instanceof FixedWindows || fn instanceof SlidingWindows || fn instanceof Sessions;
}

try {
  printPlan(rel);
} catch (UnsupportedOperationException e) {
  if (e.getMessage().startsWith("Unknown window function")) {
    // explain with a generic fallback or re-window upstream
  } else throw e;
}

When it happens

Trigger: Running EXPLAIN (or any plan-explanation path) on a Beam SQL aggregation whose upstream PCollection uses a WindowFn other than fixed/sliding/session windows.

Common situations: Applying a custom WindowFn in Java and then querying that PCollection with Beam SQL; using CalendarWindows which Beam SQL's explain path does not know about.

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

• Please explicitly specify windowing in SQL query using HOP/T
• Unsupported window mapping fn: ${sideInput.windowMappingFn.u
• Cannot encode null window
• %s.verifyCompatibility() should never be called. It is a pri
• %s.getSideInputWindow() should never be called. It is a priv

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