apache/beam · error · java.lang.UnsupportedOperationException

Specifying alignment (offset) is not supported for session…

Error message

Specifying alignment (offset) is not supported for session windows

What it means

Beam SQL SESSION windowing (BeamAggregationRule.createWindowFn) accepts only the gap-duration parameter. Unlike Tumble/Hop, Sessions windows have no alignment offset, so a third parameter triggers this UnsupportedOperationException at query translation time.

Solutions

1. Remove the third (offset) argument and call SESSION with only the timestamp descriptor and gap duration.
2. Compute the desired alignment in a pre-transform (e.g. shift timestamps) since session windows are gap-driven and alignment doesn't apply.
3. Use TUMBLE or HOP instead if you specifically need window alignment/offset.
4. Validate the SQL against the Beam SQL windowing docs for supported parameter counts before running.

Example fix

-- before
SELECT ... GROUP BY SESSION(ts, INTERVAL '1' MINUTE, INTERVAL '30' SECOND)
-- after
SELECT ... GROUP BY SESSION(ts, INTERVAL '1' MINUTE)

if (functionName.equalsIgnoreCase("SESSION") && parameters.size() > 2) { throw new IllegalArgumentException("SESSION accepts only descriptor and gap duration"); }

boolean sessionArityOk = !"SESSION".equalsIgnoreCase(fnName) || parameters.size() == 2;

try { result = pipeline.apply(SqlTransform.query(sql)); } catch (UnsupportedOperationException e) { if (e.getMessage().contains("alignment (offset) is not supported for session windows")) { /* drop the offset argument */ } else { throw e; } }

When it happens

Trigger: Writing SESSION(event_ts, INTERVAL '1' MINUTE, <offset>) with three parameters; createWindowFn sees parameters.size()==3 and throws.

Common situations: Copy-pasting a TUMBLE(ts, INTERVAL '1' HOUR, INTERVAL '0' SECOND)-style call pattern to SESSION, or porting SQL from engines (e.g. some ZetaSQL/other dialects) where session windows accept an offset.

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

• Data type: not supported yet!
• Does not support table_valued function
• `ORDER BY` is only supported for
• Please explicitly specify windowing in SQL query using…
• RexNode not supported

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

Appendix: source

Thrown at sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/rule/BeamAggregationRule.java:189

        if (parameters.size() == 4) {
          slidingWindows = slidingWindows.withOffset(durationParameter(parameters, 3));
        }

        return slidingWindows;
      case SESSION:

        // Session windows, for example:
        //   aggregate events after a gap of 1 minute of no events;
        //
        // SQL Syntax:
        //   SESSION(monotonic_field, session_gap)
        //
        // Example:
        //   SESSION(event_timestamp_field, INTERVAL '1' MINUTE)

        Sessions sessions = Sessions.withGapDuration(durationParameter(parameters, 1));
        if (parameters.size() == 3) {
          throw new UnsupportedOperationException(
              "Specifying alignment (offset) is not supported for session windows");
        }

        return sessions;
      default:
        return null;
    }
  }

  private static Duration durationParameter(List<RexNode> parameters, int parameterIndex) {
    return Duration.millis(longValue(parameters.get(parameterIndex)));
  }

  private static long longValue(RexNode operand) {
    if (operand instanceof RexLiteral) {
      // @TODO: this can be simplified after CALCITE-2837
      return ((Number) RexLiteral.value(operand)).longValue();
    } else {

View on GitHub (pinned to 12126d8942)