apache/beam · error · AssertionError

Expected that the coder is deterministic

Error message

Expected that the coder is deterministic

What it means

CoderProperties.coderDeterministicInContext is a test utility asserting that a Coder is deterministic. It calls coder.verifyDeterministic() and, when the coder reports NonDeterministicException, converts it into an AssertionError with this message. The library throws it because deterministic coding is a correctness prerequisite for Beam's grouping/windowing operations.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/testing/CoderProperties.java:85

   * Verifies that for the given {@code Coder<T>}, and values of type {@code T}, if the values are
   * equal then the encoded bytes are equal, in any {@code Coder.Context}.
   */
  public static <T> void coderDeterministic(Coder<T> coder, T value1, T value2) throws Exception {
    for (Coder.Context context : ALL_CONTEXTS) {
      coderDeterministicInContext(coder, context, value1, value2);
    }
  }

  /**
   * Verifies that for the given {@code Coder<T>}, {@code Coder.Context}, and values of type {@code
   * T}, if the values are equal then the encoded bytes are equal.
   */
  public static <T> void coderDeterministicInContext(
      Coder<T> coder, Coder.Context context, T value1, T value2) throws Exception {
    try {
      coder.verifyDeterministic();
    } catch (NonDeterministicException e) {
      throw new AssertionError("Expected that the coder is deterministic", e);
    }
    assertThat("Expected that the passed in values are equal()", value1, equalTo(value2));
    assertThat(encode(coder, context, value1), equalTo(encode(coder, context, value2)));
  }

  /**
   * Verifies that for the given {@code Coder<T>}, and value of type {@code T}, encoding followed by
   * decoding yields an equal value of type {@code T}, in any {@code Coder.Context}.
   */
  public static <T> void coderDecodeEncodeEqual(Coder<T> coder, T value) throws Exception {
    for (Coder.Context context : ALL_CONTEXTS) {
      coderDecodeEncodeEqualInContext(coder, context, value);
    }
  }

  /**
   * Verifies that for the given {@code Coder<T>}, {@code Coder.Context}, and value of type {@code
   * T}, encoding followed by decoding yields an equal value of type {@code T}.

View on GitHub (pinned to 12126d8942)

Solutions

1. Fix the coder to be deterministic: sort elements before encoding, or use a deterministic representation
2. If the coder legitimately cannot be deterministic, do not assert determinism; test encode/decode round-tripping only (e.g. CoderProperties.coderDecodeEncodeEqual)
3. Wrap the non-deterministic part with a deterministic delegate (e.g. via Docker-like ordered encodings or WritableCoder over a canonical form)

Example fix

// before
coder = new MapCoder<>(StringUtf8Coder.of(), DoubleCoder.of());
CoderProperties.coderDeterministic(coder, mapValue1, mapValue2);
// after
coder = OrderedCoderedMapCoder // or sort entries in encode()
CoderProperties.coderDeterministic(sortedMapCoder, mapValue1, mapValue2);

try {
  coder.verifyDeterministic();
} catch (NonDeterministicException e) {
  throw new IllegalStateException("Refusing determinism test: " + e.getMessage(), e);
}

boolean isDeterministicSafe(Coder<?> coder) {
  return coder.consistentWithEquals() && !(coder instanceof DoubleCoder)
      && !(coder instanceof BigDecimalCoder);
}

try {
  CoderProperties.coderDeterministic(coder, v1, v2);
} catch (AssertionError e) {
  throw new AssertionError("Coder " + coder + " is non-deterministic: fix encode() ordering", e.getCause());
}

When it happens

Trigger: Calling CoderProperties.coderDeterministic(...) or coderDeterministicInContext(coder, context, value1, value2) in a unit test where coder.verifyDeterministic() throws NonDeterministicException (e.g. double, BigDecimal, or custom coders that encode unordered structures).

Common situations: Writing custom coder tests for coders over doubles, maps, or user classes whose encoded form depends on iteration order; accidentally testing a non-deterministic coder with this assertion helper.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• the keyCoder of a GroupByEncryptedKey must be deterministic
• the keyCoder of a GroupByKey must be deterministic
• Window coders must be deterministic.
• the secondary key coder of SortValues must be deterministic
• DatadogWriteError can hold arbitrary instances, which may be

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