apache/beam · error · RuntimeError

Unable to handle state requests for ProcessBundleDescriptor…

Error message

Unable to handle state requests for ProcessBundleDescriptor for bundle id %s.

What it means

This RuntimeError is thrown by ThrowingStateHandler, a CachingStateHandler subclass in the Beam SDK worker that deliberately errors on every state request. It is used in tests or fallback paths where a bundle requests state operations but the harness has no functioning state API service configured. The contextmanager form fails immediately when a bundle's process_instruction_id is entered.

Solutions

1. Provide a real state handler (GrpcStateHandler/CachingStateHandler bound to the state ApiServiceDescriptor) when constructing the SDK harness
2. Remove or rewrite stateful transforms (DoFns using beam.state) from pipelines run against this worker
3. If this occurs in tests, ensure the test provisions a state ApiServiceDescriptor before process_bundle

Example fix

// before
state_handler = ThrowingStateHandler()
// after
state_handler = CachingStateHandler(state_api_service_descriptor)

assert isinstance(state_handler, (GrpcStateHandler, CachingStateHandler)), 'state handler must serve state requests'

def has_state_service(handler): return not isinstance(handler, ThrowingStateHandler)

try:
  with handler.process_instruction_id(bundle_id, cache_tokens):
    ...
except RuntimeError as e:
  log.error('state handling unavailable: %s', e)
  raise

When it happens

Trigger: A worker is constructed with ThrowingStateHandler (no state ApiServiceDescriptor wired) and the runner sends a ProcessBundleRequest whose instructions enter process_instruction_id(bundle_id, cache_tokens).

Common situations: Test harnesses or custom workers where stateful (user-state / bag-state) transforms are executed without a state gRPC service; pipeline configurations that enable state but launch a stateless harness.

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

• Already bound to %r
• bad symbol
• Cache tokens already set to
• CalcFn failed to evaluate
• Could not complete the query request

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

Appendix: source

Thrown at sdks/python/apache_beam/runners/worker/sdk_worker.py:1003

    raise NotImplementedError(type(self))

  @abc.abstractmethod
  def clear(self, state_key):
    # type: (beam_fn_api_pb2.StateKey) -> _Future
    raise NotImplementedError(type(self))

  @abc.abstractmethod
  def done(self):
    # type: () -> None
    raise NotImplementedError(type(self))


class ThrowingStateHandler(CachingStateHandler):
  """A caching state handler that errors on any requests."""
  @contextlib.contextmanager
  def process_instruction_id(self, bundle_id, cache_tokens):
    # type: (str, Iterable[beam_fn_api_pb2.ProcessBundleRequest.CacheToken]) -> Iterator[None]
    raise RuntimeError(
        'Unable to handle state requests for ProcessBundleDescriptor '
        'for bundle id %s.' % bundle_id)

  def blocking_get(
      self,
      state_key,  # type: beam_fn_api_pb2.StateKey
      coder,  # type: coder_impl.CoderImpl
  ):
    # type: (...) -> Iterable[Any]
    raise RuntimeError(
        'Unable to handle state requests for ProcessBundleDescriptor without '
        'state ApiServiceDescriptor for state key %s.' % state_key)

  def extend(
      self,
      state_key,  # type: beam_fn_api_pb2.StateKey
      coder,  # type: coder_impl.CoderImpl
      elements,  # type: Iterable[Any]

View on GitHub (pinned to 12126d8942)