apache/beam · error · ValueError

To write a GlobalWindow unbounded PCollection, triggering_fr

Error message

To write a GlobalWindow unbounded PCollection, triggering_frequency must be set and be greater than 0

What it means

When writing an unbounded (streaming) PCollection that is windowed into GlobalWindows, WriteToTransform._apply_windowing requires triggering_frequency, because GlobalWindows would otherwise buffer all records forever in sinks that must batch. The code fixes windowing into FixedWindows of size triggering_frequency with a discarding AfterWatermark trigger. Without it the write is unbounded and raises ValueError.

Source

Thrown at sdks/python/apache_beam/io/iobase.py:1239

            _finalize_write,
            self.sink,
            AsSingleton(init_result_coll),
            AsIter(write_result_coll),
            min_shards,
            AsSingleton(pre_finalize_coll)).with_output_types(str))

  def _apply_windowing(self, pcoll):
    """
    Applies windowing to an unbounded PCollection based on the sink's
    triggering frequency.
    """
    use_fixed_windows = (
        self.sink.triggering_frequency is not None and
        self.sink.triggering_frequency > 0)

    if isinstance(pcoll.windowing.windowfn, window.GlobalWindows):
      if not use_fixed_windows:
        raise ValueError(
            'To write a GlobalWindow unbounded PCollection, '
            'triggering_frequency must be set and be greater than 0')
      return pcoll | 'ApplyFixedWindows' >> core.WindowInto(
          window.FixedWindows(self.sink.triggering_frequency),
          trigger=beam.transforms.trigger.AfterWatermark(),
          accumulation_mode=beam.transforms.trigger.AccumulationMode.DISCARDING,
          allowed_lateness=beam.utils.timestamp.Duration(seconds=0))

    # Keep user-defined windowing unless triggering_frequency is specified.
    if use_fixed_windows:
      return pcoll | 'ApplyFixedWindows' >> core.WindowInto(
          window.FixedWindows(self.sink.triggering_frequency),
          trigger=beam.transforms.trigger.AfterWatermark(),
          accumulation_mode=beam.transforms.trigger.AccumulationMode.DISCARDING,
          allowed_lateness=beam.utils.timestamp.Duration(seconds=0))

    return pcoll  # Keep original windowing

View on GitHub (pinned to 12126d8942)

Solutions

1. Set triggering_frequency to a positive number of seconds on the sink, e.g. WriteToFiles(..., triggering_frequency=60).
2. Alternatively window the PCollection yourself into FixedWindows/SlidingWindows before the write.
3. If batch semantics were intended, ensure the PCollection is bounded (Read instead of a streaming source).

Example fix

# before
beam_data | WriteToFiles(path='/out')  # streaming, GlobalWindows
# after
beam_data | WriteToFiles(path='/out', triggering_frequency=60)

if pcoll.is_streaming and isinstance(pcoll.windowing.windowfn, window.GlobalWindows) and not triggering_frequency:
    raise ValueError('Set triggering_frequency > 0 for streaming GlobalWindow writes')

def needs_fixed_windows(pcoll, triggering_frequency) -> bool:
    from apache_beam.transforms import window
    return pcoll.is_streaming and isinstance(pcoll.windowing.windowfn, window.GlobalWindows) and not (triggering_frequency and triggering_frequency > 0)

try:
    out = pcoll | write_transform
except ValueError as e:
    if 'triggering_frequency' in str(e): log.error('Streaming write requires triggering_frequency')

When it happens

Trigger: Applying WriteToTransform (e.g. file-based sinks via WriteToFiles/Write) on a streaming PCollection whose windowfn is GlobalWindows while sink.triggering_frequency is None or <= 0.

Common situations: Streaming pipelines writing unbounded sources (Kafka/PubSub) to file sinks without setting triggering_frequency; copying batch write code into a streaming pipeline.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• MLTransform only supports GlobalWindows when producing artif
• GroupByKey cannot be applied to an unbounded PCollection wit
• GroupByKey cannot be applied to non-bounded PCollection in t
• UnboundedSource restriction was neither finished nor checkpo
• Watermark must be monotonically increasing.Provided watermar

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