apache/beam · error · ValueError

Watch restriction was neither claimed nor checkpointed: %r

Error message

Watch restriction was neither claimed nor checkpointed: %r

What it means

Watch's _WatchRestrictionChecker (a RestrictionChecker) requires that after each process() call the restriction was either claimed (input consumed) or checkpointed (split off). check_done() raises ValueError if neither happened, meaning the DoFn's process did not invoke the restriction protocol correctly — an internal invariant of the Watch implementation.

Source

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

            max((output.timestamp for output in self._claimed_result.outputs),
                default=None))
        if cursor is not None:
          completed = _retained(completed, cursor - self._allowed_lateness)
      residual = _PollingGrowthState(
          completed,
          _max_watermark(
              self._restriction.poll_watermark, self._claimed_result.watermark),
          self._claimed_termination_state,
          cursor)
      self._restriction = _NonPollingGrowthState(self._claimed_result)
    self._should_stop = True
    return self._restriction, residual

  def check_done(self) -> bool:
    # Called after every process(); the single claim or a split sets the flag.
    if self._should_stop:
      return True
    raise ValueError(
        'Watch restriction was neither claimed nor checkpointed: %r' %
        (self._restriction, ))

  def current_progress(self) -> 'iobase.RestrictionProgress':
    if self._should_stop:
      return iobase.RestrictionProgress(completed=1.0, remaining=0.0)
    return iobase.RestrictionProgress(completed=0.0, remaining=1.0)

  def is_bounded(self) -> bool:
    # A polling restriction is unbounded; a replay-then-stop one is bounded.
    return isinstance(self._restriction, _NonPollingGrowthState)


# ------------------------------------------------------------------------------
# Splittable DoFn (its own restriction provider).
# ------------------------------------------------------------------------------

View on GitHub (pinned to 12126d8942)

Solutions

1. Upgrade Apache Beam to the latest patch version — this invariant error is often fixed in newer releases
2. If you wrapped or subclassed Watch's DoFn/restriction, ensure check_done's contract is respected: every process() must claim or checkpoint
3. Avoid manual manipulation of the restriction; use Watch's public API (watch() PTransform) only

try:
    result = p | beam.Watch(poll_fn, poll_interval=...) 
except ValueError as e:
    if 'neither claimed nor checkpointed' in str(e):
        log.error('Watch restriction protocol violated; check Beam version / customizations')
    raise

When it happens

Trigger: process() was skipped or short-circuited without claiming the restriction (e.g. empty poll result paths not calling restriction claim/checkpoint); customizing Watch or wrapping its DoFn so the claim/checkpoint call is bypassed; runner-invoked split/checkpoint interleaving breaking the flag.

Common situations: Modifying or subclassing Watch internals; Beam version bugs where certain poll_fn results (e.g. immediately complete results) skip the claim path; unusual runner behaviors around splitting.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• unknown Watch growth state tag: %r
• Watch requires a poll_interval
• Watch allowed_lateness must not be negative, got %s
• Could not find coder for URN " + urn
• Unknown type of encoding context

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