apache/beam · error · IllegalArgumentException

SlidingWindows WindowingStrategies must have 0 <= offset <…

Error message

SlidingWindows WindowingStrategies must have 0 <= offset < period and 0 < size

What it means

SlidingWindows requires the constructor arguments to satisfy: offset >= 0, offset < period, and size > 0 (and separately period >= size elsewhere). The private SlidingWindows constructor validates these and throws IllegalArgumentException when violated, because such a windowing strategy is mathematically undefined.

Solutions

Ensure size > 0 before calling SlidingWindows.of(size)
Ensure offset < period and offset >= 0 when calling .every(period, offset)
Validate durations loaded from configuration before constructing the windowing
Swap arguments if size and period were accidentally reversed

Example fix

// before
SlidingWindows.of(Duration.ZERO).every(Duration.standardMinutes(5)) // throws
// after
if (size.isLongerThan(Duration.ZERO) && offset.isShorterThan(period)) {
  SlidingWindows.of(size).every(period, offset);
}

Defensive patterns

Strategy: validation

Validate before calling

static SlidingWindows safeSliding(Duration size, Duration period, Duration offset) {
  if (size.isShorterThan(Duration.ONE_MILLISECOND) || offset.isShorterThan(Duration.ZERO) || !offset.isShorterThan(period))
    throw new IllegalArgumentException("require size>0, 0<=offset<period");
  return SlidingWindows.of(size).every(period, offset);
}

Type guard

boolean validSliding(Duration size, Duration period, Duration offset) { return size.isLongerThan(Duration.ZERO) && !offset.isShorterThan(Duration.ZERO) && offset.isShorterThan(period); }

Try / catch

try { return SlidingWindows.of(size).every(period, offset); } catch (IllegalArgumentException e) { LOG.error("Bad sliding window params size={} period={} offset={}", size, period, offset, e); throw e; }

Prevention

Validate duration config values (>0) before constructing windowing
Do not swap size and period arguments
Add unit tests for boundary values (offset=0, offset=period, size=0)

When it happens

Trigger: Calling SlidingWindows.of(size).every(period) with a negative offset, offset >= period, or a non-positive size — e.g. SlidingWindows.of(Duration.ZERO) or every(Duration.standardMinutes(10)) with an offset of 15 minutes on a 10-minute period.

Common situations: Config-driven window sizes where a YAML/JSON value of 0 or negative slipped through; computing period/offset from unit conversions that produced zero; copy-paste swapping size and period arguments.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

Appendix: source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/windowing/SlidingWindows.java:90

  public SlidingWindows every(Duration period) {
    return new SlidingWindows(period, size, offset);
  }

  /**
   * Assigns timestamps into half-open intervals of the form [N * period + offset, N * period +
   * offset + size).
   *
   * @throws IllegalArgumentException if offset is not in [0, period)
   */
  public SlidingWindows withOffset(Duration offset) {
    return new SlidingWindows(period, size, offset);
  }

  private SlidingWindows(Duration period, Duration size, Duration offset) {
    if (offset.isShorterThan(Duration.ZERO)
        || !offset.isShorterThan(period)
        || !size.isLongerThan(Duration.ZERO)) {
      throw new IllegalArgumentException(
          "SlidingWindows WindowingStrategies must have 0 <= offset < period and 0 < size");
    }
    this.period = period;
    this.size = size;
    this.offset = offset;
  }

  @Override
  public Coder<IntervalWindow> windowCoder() {
    return IntervalWindow.getCoder();
  }

  @Override
  public Collection<IntervalWindow> assignWindows(AssignContext c) {
    return assignWindows(c.timestamp());
  }

  public Collection<IntervalWindow> assignWindows(Instant timestamp) {

View on GitHub (pinned to 12126d8942)