apache/beam · error · CoderException

Cannot encode null window

Error message

Cannot encode null window

What it means

TimestampPrefixingWindowCoder wraps a window coder and prefixes the window's maximum timestamp; null windows are not encodable, so encode throws CoderException. Neither the timestamp prefix nor the delegated windowCoder has a defined null representation.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/coders/TimestampPrefixingWindowCoder.java:54

  private final Coder<T> windowCoder;

  public static <T extends BoundedWindow> TimestampPrefixingWindowCoder<T> of(
      Coder<T> windowCoder) {
    return new TimestampPrefixingWindowCoder<>(windowCoder);
  }

  TimestampPrefixingWindowCoder(Coder<T> windowCoder) {
    this.windowCoder = windowCoder;
  }

  public Coder<T> getWindowCoder() {
    return windowCoder;
  }

  @Override
  public void encode(T value, OutputStream outStream) throws CoderException, IOException {
    if (value == null) {
      throw new CoderException("Cannot encode null window");
    }
    InstantCoder.of().encode(value.maxTimestamp(), outStream);
    windowCoder.encode(value, outStream);
  }

  @Override
  public T decode(InputStream inStream) throws CoderException, IOException {
    InstantCoder.of().decode(inStream);
    return windowCoder.decode(inStream);
  }

  @Override
  public List<? extends Coder<?>> getCoderArguments() {
    return Lists.newArrayList(windowCoder);
  }

  @Override
  public void verifyDeterministic() throws NonDeterministicException {

View on GitHub (pinned to 12126d8942)

Solutions

1. Ensure every element carries a real BoundedWindow (use GlobalWindow for unwindowed data).
2. Apply Window.into(...) so all elements get an assigned window.
3. In custom code, default null windows to GlobalWindow.INSTANCE before encoding.
4. Check state restored from old checkpoints for missing window fields.

Example fix

// before
prefixingCoder.encode(maybeNullWindow, out);
// after
BoundedWindow w = maybeNullWindow != null ? maybeNullWindow : GlobalWindow.INSTANCE;
prefixingCoder.encode((T) w, out);

if (window == null) {
  window = GlobalWindow.INSTANCE; // or throw IllegalArgumentException
}

static boolean hasWindow(BoundedWindow w) { return w != null; }

try {
  prefixingCoder.encode(window, out);
} catch (CoderException e) {
  throw new SerializationException("Null window in windowed value", e);
}

When it happens

Trigger: Calling encode(null, out) directly; windowed data structures containing a null window slot being written out; custom WindowedValue serialization with a missing window field.

Common situations: Custom code or test harnesses building WindowedValue instances with the window field left unset; deserialized state that lost its window and is re-encoded for shuffle/state; windowing logic that never called Window.into().

Related errors

• cannot encode a null String
• cannot encode a null Integer
• cannot encode a null ValueKind
• Invalid encoded string length: {}
• error when decoding a textual integer

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