apache/beam · error · IllegalStateException

Unable to find inbound data receiver for instruction %s and

Error message

Unable to find inbound data receiver for instruction %s and transform %s.

What it means

multiplexElements looks up the transform id of an inbound Elements.Data in the instruction's endpoint map and throws IllegalStateException when no inbound data receiver is registered for that (instructionId, transformId) pair. The runner/driver must register endpoints for every transform it expects data from before processing completes.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/fn/data/BeamFnDataInboundObserver.java:218

  /**
   * Dispatches the data and timers from the elements to corresponding receivers. Returns true if
   * all the endpoints are done after elements dispatching.
   */
  public boolean multiplexElements(
      Iterator<Elements.Data> dataElements, Iterator<BeamFnApi.Elements.Timers> timerElements)
      throws Exception {
    while (dataElements.hasNext()) {
      // We're careful to avoid references to the full data while processing, allowing the input
      // stream to possibly cleanup memory as it advances.
      InputStream inputStream;
      EndpointStatus<DataEndpoint<?>> endpoint;
      boolean isLast;
      {
        Elements.Data data = dataElements.next();
        isLast = data.getIsLast();
        endpoint = transformIdToDataEndpoint.get(data.getTransformId());
        if (endpoint == null) {
          throw new IllegalStateException(
              String.format(
                  "Unable to find inbound data receiver for instruction %s and transform %s.",
                  data.getInstructionId(), data.getTransformId()));
        } else if (endpoint.isDone) {
          throw new IllegalStateException(
              String.format(
                  "Received data after inbound data receiver is done for instruction %s and transform %s.",
                  data.getInstructionId(), data.getTransformId()));
        }
        inputStream = data.getData().newInput();
      }
      Coder<Object> coder = (Coder<Object>) endpoint.endpoint.getCoder();
      FnDataReceiver<Object> receiver = (FnDataReceiver<Object>) endpoint.endpoint.getReceiver();
      while (inputStream.available() > 0) {
        receiver.accept(coder.decode(inputStream));
      }
      if (isLast) {
        endpoint.isDone = true;

View on GitHub (pinned to 12126d8942)

Solutions

Register data endpoints (via the API's addBeamFnData.../processBundle instruction setup) for every transform id the harness will send.
Log and inspect the offending instructionId/transformId to find which registration was missed.
Ensure instruction ids are not reused across bundles so stale data maps to the correct endpoint set.
Catch IllegalStateException in awaitCompletion and fail the bundle with a clear runner-side error.

Example fix

// before
observer.awaitCompletion(); // ISE: unknown transform id
// after
api.addBeamFnDataEndpoint(instructionId, transformId, coder, receiver); // register before consuming
observer.awaitCompletion();

Defensive patterns

Strategy: try-catch

Validate before calling

boolean registered = endpointMap.containsKey(data.getTransformId()); if (!registered) { /* register before awaitCompletion */ }

Try / catch

try { observer.awaitCompletion(); } catch (IllegalStateException e) { failBundle(instructionId, e); }

Prevention

Register every transform's data endpoint during bundle setup
Log unknown instructionId/transformId pairs
Keep transform-id naming consistent across harness/runner versions

When it happens

Trigger: Receiving an Elements.Data whose transformId is absent from transformIdToDataEndpoint during awaitCompletion — e.g. the transform id was never registered via the API, the bundle was set up with different transform ids, or a stale/mismatched instruction's data arrives.

Common situations: Harness/runner version mismatch on transform id naming; pipeline graph changed between sends; data for an instruction whose consumer registration was skipped after poisoning.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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