apache/beam · error · ValueError

Initialize RestrictionTrackerView requires ThreadsafeRestric

Error message

Initialize RestrictionTrackerView requires ThreadsafeRestrictionTracker.

What it means

RestrictionTrackerView is a read-only view over a ThreadsafeRestrictionTracker for splittable DoFn size/watermark reporting. Its constructor type-checks the argument and raises this ValueError if it is not a ThreadsafeRestrictionTracker instance.

Source

Thrown at sdks/python/apache_beam/runners/sdf_utils.py:162

  def is_bounded(self):
    return self._restriction_tracker.is_bounded()


class RestrictionTrackerView(object):
  """A DoFn view of thread-safe RestrictionTracker.

  The RestrictionTrackerView wraps a ThreadsafeRestrictionTracker and only
  exposes APIs that will be called by a ``DoFn.process()``. During execution
  time, the RestrictionTrackerView will be fed into the ``DoFn.process`` as a
  restriction_tracker.
  """
  def __init__(
      self,
      threadsafe_restriction_tracker: ThreadsafeRestrictionTracker) -> None:
    if not isinstance(threadsafe_restriction_tracker,
                      ThreadsafeRestrictionTracker):
      raise ValueError(
          'Initialize RestrictionTrackerView requires '
          'ThreadsafeRestrictionTracker.')
    self._threadsafe_restriction_tracker = threadsafe_restriction_tracker

  def current_restriction(self):
    return self._threadsafe_restriction_tracker.current_restriction()

  def try_claim(self, position):
    return self._threadsafe_restriction_tracker.try_claim(position)

  def defer_remainder(self, deferred_time=None):
    self._threadsafe_restriction_tracker.defer_remainder(deferred_time)

  def is_bounded(self):
    self._threadsafe_restriction_tracker.is_bounded()


class ThreadsafeWatermarkEstimator(object):

View on GitHub (pinned to 12126d8942)

Solutions

Wrap the tracker in ThreadsafeRestrictionTracker first, then pass it to RestrictionTrackerView
Ensure your DoFn creates the threadsafe wrapper once and derives the view from it

Example fix

// before
return RestrictionTrackerView(OffsetRangeTracker(self._range))
// after
self._tracker = ThreadsafeRestrictionTracker(OffsetRangeTracker(self._range))
return RestrictionTrackerView(self._tracker)

Defensive patterns

Strategy: type-guard

Validate before calling

isinstance(t, ThreadsafeRestrictionTracker)  # check before constructing view

Type guard

from apache_beam.runners.sdf_utils import ThreadsafeRestrictionTracker
def is_threadsafe_tracker(x) -> bool:
    return isinstance(x, ThreadsafeRestrictionTracker)

Try / catch

try:
    view = RestrictionTrackerView(t)
except ValueError as e:
    if 'ThreadsafeRestrictionTracker' in str(e):
        t = ThreadsafeRestrictionTracker(t._restriction_tracker)  # or rebuild
        view = RestrictionTrackerView(t)
    else:
        raise

Prevention

Always create ThreadsafeRestrictionTracker before the view
Store the threadsafe tracker on self and derive the view from it
Follow the sdf_utils wrapper pattern in custom SDFs

When it happens

Trigger: Instantiating RestrictionTrackerView(tracker) with a plain RestrictionTracker (not wrapped in ThreadsafeRestrictionTracker), None, or any other tracker type.

Common situations: Implementing a custom splittable DoFn's restriction_tracker() method and returning the raw tracker instead of the threadsafe wrapper required by the framework.

Related errors

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