apache/beam · error · IllegalStateException

Unable to find inbound timer receiver for instruction %s, tr

Error message

Unable to find inbound timer receiver for instruction %s, transform %s, and timer family %s.

What it means

multiplexElements throws IllegalStateException when the transform id of an inbound Elements.Timers message has no timer-family endpoint map registered for the instruction. No timer receivers were configured for that transform.

Source

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

        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;
        numEndpointsThatAreIncomplete -= 1;
      }
    }

    while (timerElements.hasNext()) {
      Elements.Timers timers = timerElements.next();
      Map<String, EndpointStatus<TimerEndpoint<?>>> timerFamilyIdToEndpoints =
          transformIdToTimerFamilyIdToTimerEndpoint.get(timers.getTransformId());
      if (timerFamilyIdToEndpoints == null) {
        throw new IllegalStateException(
            String.format(
                "Unable to find inbound timer receiver for instruction %s, transform %s, and timer family %s.",
                timers.getInstructionId(), timers.getTransformId(), timers.getTimerFamilyId()));
      }
      EndpointStatus<TimerEndpoint<?>> endpoint =
          timerFamilyIdToEndpoints.get(timers.getTimerFamilyId());
      if (endpoint == null) {
        throw new IllegalStateException(
            String.format(
                "Unable to find inbound timer receiver for instruction %s, transform %s, and timer family %s.",
                timers.getInstructionId(), timers.getTransformId(), timers.getTimerFamilyId()));
      } else if (endpoint.isDone) {
        throw new IllegalStateException(
            String.format(
                "Received timer after inbound timer receiver is done for instruction %s, transform %s, and timer family %s.",
                timers.getInstructionId(), timers.getTransformId(), timers.getTimerFamilyId()));
      }
      InputStream inputStream = timers.getTimers().newInput();

View on GitHub (pinned to 12126d8942)

Solutions

1. Register timer-family endpoints for every transform expected to emit timers (setup for process bundle with timers).
2. Confirm transform ids in the sent Elements.Timers match the registered endpoint map keys.
3. Ensure instruction ids are unique per bundle so stale timer data doesn't hit the wrong map.
4. Catch IllegalStateException in awaitCompletion and fail the bundle with a descriptive error.

Example fix

// before
observer.awaitCompletion(); // ISE: no timer endpoints for transform
// after
api.addBeamFnTimerEndpoint(instructionId, transformId, timerFamilyId, coder, timerReceiver);
observer.awaitCompletion();

boolean ok = transformIdToTimerFamilyIdToTimerEndpoint.containsKey(timers.getTransformId()); if (!ok) { registerTimerEndpoints(...); }

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

When it happens

Trigger: Receiving Elements.Timers whose transformId is missing from transformIdToTimerFamilyIdToTimerEndpoint during awaitCompletion — timers streamed for a transform with no registered timer endpoints, or stale instruction data.

Common situations: Bundle registered without timer receivers but the harness streams timers; transform id mismatch between runner and harness; data for a poisoned/reused instruction id.

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

• Unable to find inbound data receiver for instruction %s and
• Received timer after inbound timer receiver is done for inst
• Instruction id was poisoned
• Unregistering consumer which was not registered.
• PoisonedException

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