apache/beam · error · IncompatibleWindowException

%s is not compatible with %s

Error message

%s is not compatible with %s

What it means

WindowFn.verifyCompatibility() checks whether two window functions can be composed in the same pipeline stage (e.g. when re-windowing or merging inputs/outputs). If this.isCompatible(other) returns false, it throws IncompatibleWindowException naming the two WindowFn classes. This guards against semantically meaningless combinations such as merging a fixed-windows PCollection with a sliding-windows view.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/windowing/WindowFn.java:107

  /**
   * Returns whether this performs the same merging as the given {@code WindowFn}.
   *
   * @deprecated please override verifyCompatibility to throw a useful error message; we will remove
   *     isCompatible at version 3.0.0
   */
  @Deprecated
  public abstract boolean isCompatible(WindowFn<?, ?> other);

  /**
   * Throw {@link IncompatibleWindowException} if this WindowFn does not perform the same merging as
   * the given ${@code WindowFn}.
   *
   * @throws IncompatibleWindowException if compared WindowFns are not compatible.
   */
  public void verifyCompatibility(WindowFn<?, ?> other) throws IncompatibleWindowException {
    if (!this.isCompatible(other)) {
      throw new IncompatibleWindowException(
          other,
          String.format(
              "%s is not compatible with %s",
              this.getClass().getSimpleName(), other.getClass().getSimpleName()));
    }
  }

  /** Returns the {@link Coder} used for serializing the windows used by this windowFn. */
  public abstract Coder<W> windowCoder();

  /**
   * Returns the default {@link WindowMappingFn} to use to map main input windows to side input
   * windows. This should accept arbitrary main input windows, and produce a {@link BoundedWindow}
   * that can be produced by this {@link WindowFn}.
   */
  public abstract WindowMappingFn<W> getDefaultWindowMappingFn();

  /** Returns true if this {@code WindowFn} never needs to merge any windows. */

View on GitHub (pinned to 12126d8942)

Solutions

1. Insert an explicit re-windowing step (apply Window.into(newFn)) so the input is transformed to the target windowing before composition.
2. Use window functions that are mutually compatible (same WindowFn class and compatible parameters as per isCompatible()).
3. Catch IncompatibleWindowException in pipeline-construction helpers and surface a clearer message about which WindowFns conflict.

Example fix

// before
PCollection<T> out = fixedWindowed.apply(Window.<T>into(SlidingWindows.of(StandardMinutes.of(10)).every(StandardMinutes.of(5)))); // combined elsewhere with incompatible fn
// after
PCollection<T> rewindowed = fixedWindowed.apply(Window.<T>into(SlidingWindows.of(StandardMinutes.of(10)).every(StandardMinutes.of(5))));
PCollection<T> out = rewindowed.apply(...); // only compose after the explicit re-windowing

// pre-check (requires access): if (!fnA.isCompatible(fnB)) { reWindow first }

try {
  windowFn.verifyCompatibility(other);
} catch (IncompatibleWindowException e) {
  // insert Window.into(...) re-windowing step or fail with explanatory message
}

When it happens

Trigger: Applying Window.into/setWindowFn with a WindowFn incompatible with the input's existing windowing strategy (WindowFn.isCompatible returned false); also triggered by transforms like GBK/re-windowing that call verifyCompatibility during expand().

Common situations: Combining or following a Window transform with a differently-shaped WindowFn (FixedWindows vs SlidingWindows, different gaps); passing a re-windowed PCollection into GroupByKey; library code composing user-supplied window functions.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• Provided coders for type arguments of %s contain incompatibi
• Can't cast non-numeric types: +input
• Can't cast numbers to non-numeric type: +output
• KeepFn %s must return a boolean, but returns %s instead.
• Distinct does not support merging windowing strategies, exce

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