apache/beam · error · IllegalArgumentException

Could not decode provided windows with the provided window…

Error message

Could not decode provided windows with the provided window coder

What it means

WindowSupplier.get lazily decodes its pre-encoded window bytes; if CoderUtils.decodeFromByteArray fails for any entry it throws this IllegalArgumentException wrapping the CoderException. Indicates the stored bytes no longer match the coder being used.

Solutions

Ensure the same Coder instance/type is used to construct and to decode the WindowSupplier
Align Beam SDK versions across the pipeline that serialized the WindowSupplier
Rebuild the WindowSupplier via WindowSupplier.of with matching coder and windows

Defensive patterns

Strategy: try-catch

Try / catch

try {
  supplier.get();
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("Could not decode provided windows")) {
    throw new IllegalStateException("WindowSupplier coder/bytes mismatch; rebuild supplier", e);
  }
  throw e;
}

Prevention

Use the identical Coder instance at of() time and at decode time
Avoid serializing WindowSupplier across incompatible Beam versions
Rebuild WindowSupplier.of(...) after any coder change

When it happens

Trigger: decodeWindows() invoked on first get() where encodedWindows bytes cannot be decoded by the supplied coder (corrupted bytes, coder changed since of() was called, Java serialization deserialization across class changes).

Common situations: WindowSupplier serialized/deserialized in a pipeline where the coder class changed between versions, or a coder whose decode is stricter than its encode.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/testing/WindowSupplier.java:82

    this.encodedWindows = encodedWindows;
  }

  @Override
  public Collection<BoundedWindow> get() {
    if (windows == null) {
      decodeWindows();
    }
    return windows;
  }

  private synchronized void decodeWindows() {
    if (windows == null) {
      ImmutableList.Builder<BoundedWindow> windowsBuilder = ImmutableList.builder();
      for (byte[] encoded : encodedWindows) {
        try {
          windowsBuilder.add(CoderUtils.decodeFromByteArray(coder, encoded));
        } catch (CoderException e) {
          throw new IllegalArgumentException(
              "Could not decode provided windows with the provided window coder", e);
        }
      }
      this.windows = windowsBuilder.build();
    }
  }
}

View on GitHub (pinned to 12126d8942)