apache/beam · error · RuntimeError

Unable to handle state requests for ProcessBundleDescriptor.

Error message

Unable to handle state requests for ProcessBundleDescriptor.

What it means

ThrowingStateHandler.done always raises as a final guard: any lifecycle completion of state handling proves state requests were attempted against a descriptor without a state service. It fires when the harness finalizes state handling for a bundle.

Solutions

1. Replace ThrowingStateHandler with GrpcStateHandler/CachingStateHandler at harness construction
2. Remove stateful stages from the pipeline or use a runner that supports state
3. Verify worker startup flags pass the state ApiServiceDescriptor

assert state_api_service_descriptor is not None, 'descriptor missing state service'

try:
  handler.done()
except RuntimeError as e:
  log.error('state handler teardown failed: %s', e)
  raise

When it happens

Trigger: Calling done() on ThrowingStateHandler at bundle teardown after any state-enabled bundle was processed with this stub handler.

Common situations: Same as sibling errors: stateful pipelines executed on harnesses lacking state ApiServiceDescriptor configuration.

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
• At least one owner must be registered.
• Buffer counter not initialized for UUID:
• Bundle is not in a finalizable state for
• Cache tokens already set to

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

Appendix: source

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

      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 '
        'state ApiServiceDescriptor for state key %s.' % state_key)

  def done(self):
    # type: () -> None
    raise RuntimeError(
        'Unable to handle state requests for ProcessBundleDescriptor.')


class GrpcStateHandler(StateHandler):

  _DONE = Sentinel.sentinel

  def __init__(self, state_stub):
    # type: (beam_fn_api_pb2_grpc.BeamFnStateStub) -> None
    self._lock = threading.Lock()
    self._state_stub = state_stub
    self._requests = queue.Queue(
    )  # type: queue.Queue[Union[beam_fn_api_pb2.StateRequest, Sentinel]]
    self._responses_by_id = {}  # type: Dict[str, _Future]
    self._last_id = 0
    self._exception = None  # type: Optional[Exception]
    self._context = threading.local()
    self.start()

View on GitHub (pinned to 12126d8942)