apache/beam · error · IllegalArgumentException

Cannot convert unknown %s to %s: %s

Error message

Cannot convert unknown %s to %s: %s

What it means

WindowingStrategyTranslation.fromProto converts a RunnerApi.AccumulationMode proto enum into the Java SDK AccumulationMode enum. When the proto value is UNRECOGNIZED (or hits an unhandled case) — typically because the runner/SDK linking against older generated proto code encounters a newer enum value — it throws this IllegalArgumentException naming both classes and the offending value.

Source

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

import org.joda.time.Duration;

/** Utilities for working with {@link WindowingStrategy WindowingStrategies}. */
public class WindowingStrategyTranslation implements Serializable {

  public static AccumulationMode fromProto(RunnerApi.AccumulationMode.Enum proto) {
    switch (proto) {
      case DISCARDING:
        return AccumulationMode.DISCARDING_FIRED_PANES;
      case ACCUMULATING:
        return AccumulationMode.ACCUMULATING_FIRED_PANES;
      case RETRACTING:
        return AccumulationMode.RETRACTING_FIRED_PANES;
      case UNRECOGNIZED:
      default:
        // Whether or not it is proto that cannot recognize it (due to the version of the
        // generated code we link to) or the switch hasn't been updated to handle it,
        // the situation is the same: we don't know what this OutputTime means
        throw new IllegalArgumentException(
            String.format(
                "Cannot convert unknown %s to %s: %s",
                RunnerApi.AccumulationMode.class.getCanonicalName(),
                AccumulationMode.class.getCanonicalName(),
                proto));
    }
  }

  public static RunnerApi.AccumulationMode.Enum toProto(AccumulationMode accumulationMode) {
    switch (accumulationMode) {
      case DISCARDING_FIRED_PANES:
        return RunnerApi.AccumulationMode.Enum.DISCARDING;
      case ACCUMULATING_FIRED_PANES:
        return RunnerApi.AccumulationMode.Enum.ACCUMULATING;
      case RETRACTING_FIRED_PANES:
        return RunnerApi.AccumulationMode.Enum.RETRACTING;
      default:
        throw new IllegalArgumentException(

View on GitHub (pinned to 12126d8942)

Solutions

1. Align Beam versions: run the pipeline with an SDK version equal to or newer than the one that produced the proto.
2. Upgrade the runner's Beam dependency so its generated RunnerApi protos recognize the enum value.
3. Re-translate the pipeline so the windowing strategy uses a supported accumulation mode.
4. If you control the graph, set an explicitly supported accumulation mode (DISCARDING_FIRED_PANES / ACCUMULATING_FIRED_PANES / RETRACTING_FIRED_PANES).

Example fix

// before: newer SDK proto -> older runner
// runner on Beam 2.x cannot recognize a new AccumulationMode enum value
// after: upgrade the runner's Beam dependency to >= the submitting SDK version
implementation 'org.apache.beam:beam-runners-direct-java:2.50.0' // match SDK version

// Pre-check that the proto enum is resolvable before translation
if (proto == RunnerApi.AccumulationMode.Enum.UNRECOGNIZED) {
  throw new IllegalArgumentException("Unknown AccumulationMode proto value; upgrade Beam dependency");
}

try {
  mode = WindowingStrategyTranslation.accumulationMode(strategyProto);
} catch (IllegalArgumentException e) {
  if (String.valueOf(e.getMessage()).contains("Cannot convert unknown")) {
    // upgrade runner Beam dependency to >= submitting SDK, then resubmit
  }
  throw e;
}

When it happens

Trigger: fromProto(RunnerApi.AccumulationMode) is called (via accumulationMode()/closingBehavior()/onTimeBehavior() path) with a proto enum value the linked generated code cannot recognize, or a value added in a newer Beam proto that this switch does not handle.

Common situations: Job submitted by a newer Beam SDK to an older runner/expansion service; proto descriptor version skew; hand-crafted strategy protos with invalid enum numbers.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unknown ValueKind number: {}
• Cannot convert unknown %s to %s: %s
• Unknown accumulation mode [${accumulationMode}]
• Unrecognized value for stable unique names:
• Cannot encode null window

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