apache/beam · error · ValueError

Watch requires a poll_interval

Error message

Watch requires a poll_interval

What it means

beam.Watch's underlying transform requires an explicit poll_interval (how long to wait between calls to the poll function). Since no sensible default exists (it depends on the external source), __init__ raises ValueError when poll_interval is None.

Source

Thrown at sdks/python/apache_beam/io/watch.py:858

      Widen it for a source whose outputs arrive out of order, at the cost of a
      larger state. Ignored unless ``timestamp_cursor`` is set; defaults to
      zero.
    now_fn: clock used for termination decisions; tests can inject one.
  """
  def __init__(
      self,
      poll_fn: Callable[[Any], PollResult],
      poll_interval,
      termination: Optional[TerminationCondition] = None,
      output_coder: Optional[Coder] = None,
      output_key_fn: Optional[Callable[[Any], Any]] = None,
      output_key_coder: Optional[Coder] = None,
      timestamp_cursor: bool = False,
      allowed_lateness=0,
      now_fn: Optional[Callable[[], float]] = None):
    super().__init__()
    if poll_interval is None:
      raise ValueError('Watch requires a poll_interval')
    allowed_lateness = _as_duration(allowed_lateness)
    if allowed_lateness < Duration(0):
      raise ValueError(
          'Watch allowed_lateness must not be negative, got %s' %
          allowed_lateness)
    self._poll_fn = poll_fn
    self._poll_interval = _as_duration(poll_interval)
    self._termination = termination or never()
    self._output_coder = output_coder
    self._output_key_fn = output_key_fn
    self._output_key_coder = output_key_coder
    self._timestamp_cursor = timestamp_cursor
    self._allowed_lateness = allowed_lateness
    self._now = now_fn

  def expand(self, pcoll):
    output_coder = self._output_coder
    if output_coder is None and isinstance(self._poll_fn, PollFn):

View on GitHub (pinned to 12126d8942)

Solutions

1. Pass poll_interval explicitly, e.g. beam.Watch(source, event_time_fn=..., poll_interval=30)
2. Check your configuration loading — ensure the interval config key is populated before constructing the transform
3. Use a sane default like poll_interval=30 (seconds) for external-system polling

Example fix

// before
result = (p | beam.Watch(poll_fn))
// after
result = (p | beam.Watch(poll_fn, poll_interval=30))

if poll_interval is None:
    raise ValueError('poll_interval is required for Watch')

try:
    step = beam.Watch(poll_fn, poll_interval=interval)
except ValueError:
    step = beam.Watch(poll_fn, poll_interval=30)

When it happens

Trigger: Constructing beam.Watch (or _Pollers/wrapper) without passing poll_interval, e.g. beam.Watch(source) with only source/output_fn arguments and no poll_interval keyword.

Common situations: Users forgetting that unlike some polling utilities Watch has no default poll interval; copying old examples where poll_interval was optional; passing None explicitly from a config value that failed to load.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• You have to supply one of 'by' and 'level'
• The TableRowJsonCoder requires a table schema for encoding o
• A BigQuery table or a query must be specified
• unknown Watch growth state tag: %r
• Watch restriction was neither claimed nor checkpointed: %r

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