What causes "Expected a %s with components but received %s" in apache/beam?

Ensure the message was built with WINDOWING_STRATEGY set together with its components (use fromProto(windowingStrategy, components) output as input).

apache/beam · error · IllegalArgumentException

Expected a %s with components but received %s

Error message

Expected a %s with components but received %s

What it means

Thrown by the top-level WindowingStrategyTranslation.fromProto(MessageWithComponents) overload when the incoming message's oneof root is not the WINDOWING_STRATEGY case. The method expects a message that bundles a WindowingStrategy with its Components so PCollections can be rehydrated; receiving any other root case means the caller passed the wrong wrapper type.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/util/construction/WindowingStrategyTranslation.java:328

            .setWindowCoderId(components.registerCoder(windowFn.windowCoder()))
            .setEnvironmentId(environmentId);

    return windowingStrategyProto.build();
  }

  /**
   * Converts from a {@link RunnerApi.WindowingStrategy} accompanied by {@link Components} to the
   * SDK's {@link WindowingStrategy}.
   */
  public static WindowingStrategy<?, ?> fromProto(RunnerApi.MessageWithComponents proto)
      throws InvalidProtocolBufferException {
    switch (proto.getRootCase()) {
      case WINDOWING_STRATEGY:
        return fromProto(
            proto.getWindowingStrategy(),
            RehydratedComponents.forComponents(proto.getComponents()));
      default:
        throw new IllegalArgumentException(
            String.format(
                "Expected a %s with components but received %s",
                RunnerApi.WindowingStrategy.class.getCanonicalName(), proto));
    }
  }

  /**
   * Converts from {@link RunnerApi.WindowingStrategy} to the SDK's {@link WindowingStrategy} using
   * the provided components to dereferences identifiers found in the proto.
   */
  public static WindowingStrategy<?, ?> fromProto(
      RunnerApi.WindowingStrategy proto, RehydratedComponents components)
      throws InvalidProtocolBufferException {

    FunctionSpec windowFnSpec = proto.getWindowFn();
    WindowFn<?, ?> windowFn = windowFnFromProto(windowFnSpec);
    TimestampCombiner timestampCombiner = timestampCombinerFromProto(proto.getOutputTime());
    AccumulationMode accumulationMode = fromProto(proto.getAccumulationMode());

View on GitHub (pinned to 12126d8942)

Solutions

Ensure the message was built with WINDOWING_STRATEGY set together with its components (use fromProto(windowingStrategy, components) output as input).
Check that the serialization/deserialization pair populates the same oneof case.
Call the two-argument fromProto(WindowingStrategy, RehydratedComponents) directly if you already have the pieces.
Log/inspect proto.getRootCase() and getAllFields() to confirm what was actually received.

Example fix

// before
WindowingStrategy<?> ws = WindowingStrategyTranslation.fromProto(bareStrategyProto);
// after
WindowingStrategy<?> ws = WindowingStrategyTranslation.fromProto(
    MessageWithComponents.ofWindowingStrategy(strategyProto, componentsProto));

Defensive patterns

Strategy: validation

Validate before calling

if (proto == null || proto.getRootCase() != RunnerApi.MessageWithComponents.RootCase.WINDOWING_STRATEGY) throw new IllegalArgumentException("Expected MessageWithComponents with WINDOWING_STRATEGY root");

Type guard

boolean hasWindowingStrategyRoot(RunnerApi.MessageWithComponents m) { return m != null && m.getRootCase() == RunnerApi.MessageWithComponents.RootCase.WINDOWING_STRATEGY; }

Try / catch

try { ws = WindowingStrategyTranslation.fromProto(messageWithComponents); } catch (IllegalArgumentException e) { log.error("Wrong root case {}; use the (WindowingStrategy, RehydratedComponents) overload", messageWithComponents.getRootCase(), e); throw e; }

Prevention

Round-trip protos through the official toProto/fromProto pairs instead of hand-building messages
Check getRootCase() after deserialization to detect unpopulated oneofs
Use MessageWithComponents factory helpers when bundling strategy + components

When it happens

Trigger: Calling fromProto(proto) where proto.getRootCase() is not WINDOWING_STRATEGY — e.g. passing a bare components message, an empty/incorrectly built MessageWithComponents, or a message from a different oneof union.

Common situations: Hand-constructing pipeline protos in tests; runner code that mis-assembles the oneof field; decoding a proto that was never populated because serialization failed upstream.

Related errors

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