apache/beam · error · ValueError

The size parameter must be strictly positive.

Error message

The size parameter must be strictly positive.

What it means

FixedWindows requires the window size to be strictly positive (size > 0); the constructor raises ValueError otherwise. The size defines the fixed window width in seconds and zero/negative widths are meaningless.

Source

Thrown at sdks/python/apache_beam/transforms/window.py:417

  Attributes:
    size: Size of the window as seconds.
    offset: Offset of this window as seconds. Windows start at
      t=N * size + offset where t=0 is the UNIX epoch. The offset must be a
      value in range [0, size). If it is not it will be normalized to this
      range.
  """
  def __init__(self, size: DurationTypes, offset: TimestampTypes = 0):
    """Initialize a ``FixedWindows`` function for a given size and offset.

    Args:
      size (int): Size of the window in seconds.
      offset(int): Offset of this window as seconds. Windows start at
        t=N * size + offset where t=0 is the UNIX epoch. The offset must be a
        value in range [0, size). If it is not it will be normalized to this
        range.
    """
    if size <= 0:
      raise ValueError('The size parameter must be strictly positive.')
    self.size = Duration.of(size)
    self.offset = Timestamp.of(offset) % self.size

  def assign(self, context: WindowFn.AssignContext) -> list[IntervalWindow]:
    timestamp = context.timestamp
    start = timestamp - (timestamp - self.offset) % self.size
    return [IntervalWindow(start, start + self.size)]

  def get_window_coder(self) -> coders.IntervalWindowCoder:
    return coders.IntervalWindowCoder()

  def __eq__(self, other):
    if type(self) == type(other) == FixedWindows:
      return self.size == other.size and self.offset == other.offset

  def __hash__(self):
    return hash((self.size, self.offset))

View on GitHub (pinned to 12126d8942)

Solutions

1. Pass a strictly positive duration, e.g. FixedWindows(60)
2. Validate the config value before constructing: assert window_seconds > 0
3. Fix unit conversion so the duration isn't truncated to 0 (use timedelta.total_seconds())

Example fix

// before
window_secs = int(os.getenv('WINDOW_SECS', '0'))
beam.WindowInto(FixedWindows(window_secs))
// after
window_secs = int(os.getenv('WINDOW_SECS', '60'))
assert window_secs > 0
beam.WindowInto(FixedWindows(window_secs))

if window_size <= 0:
    raise ValueError('window_size must be > 0')

def valid_window_size(v): return isinstance(v, (int, float)) and v > 0

When it happens

Trigger: FixedWindows(0), FixedWindows(-30), or size computed from a config/flag that resolved to 0 (e.g. int('0'), a missing timedelta converted to seconds).

Common situations: Window duration parsed from CLI/env defaulting to 0; dividing a total duration by a count that is 0 or huge; unit confusion where milliseconds value was meant as seconds and rounded to 0.

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

• min_batch_size must be >= 1, got {min_batch_size}
• max_batch_size ({max_batch_size}) must be >= min_batch_size
• max_batch_weight must be >= 1, got {max_batch_weight}
• window_coder should not be None
• If `num_buckets` is set, it has to be an integer greater tha

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