apache/beam · error · IllegalArgumentException

Unknown %s: %s

Error message

Unknown %s: %s

What it means

Thrown by WindowingStrategyTranslation.toProto when a TimestampCombiner value has no mapping to a RunnerApi.OutputTime.Enum proto value. The switch in the translation table only covers the known combiners; anything else (typically a newer SDK combiner sent to an older runner) falls into the default branch. It signals the Java TimestampCombiner enum and the Beam portability proto have drifted out of sync.

Source

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

        throw new IllegalArgumentException(
            String.format(
                "Cannot convert unknown %s to %s: %s",
                RunnerApi.OnTimeBehavior.class.getCanonicalName(),
                OnTimeBehavior.class.getCanonicalName(),
                proto));
    }
  }

  public static RunnerApi.OutputTime.Enum toProto(TimestampCombiner timestampCombiner) {
    switch (timestampCombiner) {
      case EARLIEST:
        return OutputTime.Enum.EARLIEST_IN_PANE;
      case END_OF_WINDOW:
        return OutputTime.Enum.END_OF_WINDOW;
      case LATEST:
        return OutputTime.Enum.LATEST_IN_PANE;
      default:
        throw new IllegalArgumentException(
            String.format(
                "Unknown %s: %s", TimestampCombiner.class.getSimpleName(), timestampCombiner));
    }
  }

  public static TimestampCombiner timestampCombinerFromProto(RunnerApi.OutputTime.Enum proto) {
    switch (proto) {
      case EARLIEST_IN_PANE:
        return TimestampCombiner.EARLIEST;
      case END_OF_WINDOW:
        return TimestampCombiner.END_OF_WINDOW;
      case LATEST_IN_PANE:
        return TimestampCombiner.LATEST;
      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

View on GitHub (pinned to 12126d8942)

Solutions

1. Align beam-sdks-java-core and beam-model versions so TimestampCombiner and RunnerApi.OutputTime.Enum are from the same release.
2. Pin the runner and SDK harness to the same Beam version used at pipeline construction time.
3. If you legitimately added a new TimestampCombiner, add the corresponding case mapping to RunnerApi.OutputTime.Enum in WindowingStrategyTranslation.toProto.
4. Check for shaded/duplicated beam-model jars on the classpath bringing an older proto enum.

Example fix

// before (mismatched versions)
implementation "org.apache.beam:beam-sdks-java-core:2.50.0"
implementation "org.apache.beam:beam-model-pipeline:2.40.0"
// after
implementation "org.apache.beam:beam-sdks-java-core:2.50.0"
implementation "org.apache.beam:beam-model-pipeline:2.50.0"

import static org.apache.beam.sdk.util.construction.WindowingStrategyTranslation.*;
Set<TimestampCombiner> supported = EnumSet.of(TimestampCombiner.EARLIEST, TimestampCombiner.LATEST);
if (!supported.contains(strategy.getTimestampCombiner())) throw new IllegalArgumentException("Unsupported TimestampCombiner for this proto version: " + strategy.getTimestampCombiner());

boolean isMappable(TimestampCombiner c) { switch (c) { case EARLIEST: case LATEST: return true; default: return false; } }

try { proto = WindowingStrategyTranslation.windowingStrategyProto(strategy); } catch (IllegalArgumentException e) { log.error("TimestampCombiner not representable in proto: {}", strategy.getTimestampCombiner(), e); throw e; }

When it happens

Trigger: Calling WindowingStrategyTranslation.toProto (directly or via windowingStrategyProto) on a WindowingStrategy whose timestampCombiner is a TimestampCombiner value not handled by the switch, e.g. a newly added combiner running against an older generated RunnerApi protos jar.

Common situations: Mixing Beam SDK versions across SDK harness and runner; upgrading the Beam Java SDK while a pinned beam-model pipeline jar is stale; custom or vendored TimestampCombiner values.

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

• Cannot encode null window
• %s.verifyCompatibility() should never be called. It is a pri
• %s.getSideInputWindow() should never be called. It is a priv
• Expected a %s with components but received %s
• Unknown or unsupported WindowFn:

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