apache/beam · error · RuntimeError

Unable to handle state requests for ProcessBundleDescriptor…

Error message

Unable to handle state requests for ProcessBundleDescriptor without state ApiServiceDescriptor for state key %s.

What it means

ThrowingStateHandler.blocking_get always raises: it is a placeholder for a state handler serving a ProcessBundleDescriptor that has no state ApiServiceDescriptor, so blocking state reads cannot be served. Throwing immediately surfaces the misconfiguration instead of hanging or silently returning wrong data.

Solutions

Wire a functional GrpcStateHandler to the descriptor's state_api_service_descriptor
Refactor the DoFn to avoid state API reads (e.g. side inputs or pass-through data)
Update the runner/harness so the descriptor includes a state ApiServiceDescriptor

Example fix

// before
handler = ThrowingStateHandler()
value = list(handler.blocking_get(state_key, coder))
// after
handler = GrpcStateHandler(state_descriptor.state_api_service_descriptor)
value = list(handler.blocking_get(state_key, coder))

Defensive patterns

Strategy: try-catch

Validate before calling

if descriptor.state_api_service_descriptor is None: raise ConfigError('state requested but no state ApiServiceDescriptor')

Try / catch

try:
  value = handler.blocking_get(state_key, coder)
except RuntimeError as e:
  log.error('state reads unsupported: %s', e)
  raise

Prevention

Validate descriptors declare a state ApiServiceDescriptor before processing stateful stages
Avoid beam.state transforms on runners without state support
Cover stateful DoFns with integration tests against a real state service

When it happens

Trigger: Calling blocking_get(state_key, coder) on a ThrowingStateHandler, which happens when pipeline code reads user state (ReadMaterializedState / ReadModifyWriteState) during bundle execution.

Common situations: Stateful streaming pipelines deployed on a runner whose worker harness was started without state API support; tests exercising bundle execution paths without a state service.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

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

    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]
  ):
    # type: (...) -> _Future
    raise RuntimeError(
        'Unable to handle state requests for ProcessBundleDescriptor without '
        'state ApiServiceDescriptor for state key %s.' % state_key)

  def clear(self, state_key):
    # type: (beam_fn_api_pb2.StateKey) -> _Future
    raise RuntimeError(
        'Unable to handle state requests for ProcessBundleDescriptor without '

View on GitHub (pinned to 12126d8942)