{"record":{"id":"1c45adc845befce9","repo":"apache/beam","slug":"ordering-of-entries-in-a-map-may-be-non-deterministic","errorCode":null,"errorMessage":"Ordering of entries in a Map may be non-deterministic.","messagePattern":"Ordering of entries in a Map may be non-deterministic\\.","errorType":"exception","errorClass":"NonDeterministicException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/coders/MapCoder.java","lineNumber":141,"sourceCode":"   * {@inheritDoc}\n   *\n   * @return a {@link List} containing the key coder at index 0 at the and value coder at index 1.\n   */\n  @Override\n  public List<? extends Coder<?>> getCoderArguments() {\n    return Arrays.asList(keyCoder, valueCoder);\n  }\n\n  /**\n   * {@inheritDoc}\n   *\n   * @throws NonDeterministicException always. Not all maps have a deterministic encoding. For\n   *     example, {@code HashMap} comparison does not depend on element order, so two {@code\n   *     HashMap} instances may be equal but produce different encodings.\n   */\n  @Override\n  public void verifyDeterministic() throws NonDeterministicException {\n    throw new NonDeterministicException(\n        this, \"Ordering of entries in a Map may be non-deterministic.\");\n  }\n\n  @Override\n  public boolean consistentWithEquals() {\n    return keyCoder.consistentWithEquals() && valueCoder.consistentWithEquals();\n  }\n\n  @Override\n  public Object structuralValue(Map<K, V> value) {\n    if (consistentWithEquals()) {\n      return value;\n    } else {\n      Map<Object, Object> ret = Maps.newHashMapWithExpectedSize(value.size());\n      for (Map.Entry<K, V> entry : value.entrySet()) {\n        ret.put(\n            keyCoder.structuralValue(entry.getKey()), valueCoder.structuralValue(entry.getValue()));\n      }","sourceCodeStart":123,"sourceCodeEnd":159,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/MapCoder.java#L123-L159","documentation":"MapCoder.verifyDeterministic() always throws NonDeterministicException because Java Maps (e.g. HashMap) iterate in arbitrary order, so encoding the same map twice can yield different bytes. Beam requires deterministic encodings in operations that group and re-encode keys (e.g. GroupByKey on coded keys) to guarantee correctness.","triggerScenarios":"Using a Map (via MapCoder) as a PCollection element or key in an operation requiring determinism, e.g. GroupByKey, Combine, or Coder.verifyDeterministic() checks during pipeline validation.","commonSituations":"Grouping records keyed by a HashMap; tests calling CoderRegistry verifyDeterministic; pipeline construction fails validation at submit time.","solutions":["Verify a deterministic coder explicitly instead: new MapCoder<>(new OrderedCoder(keyCoder), new OrderedCoder(valueCoder)).verifyDeterministic() on an ordered map type","Use a deterministic key type (e.g. a custom POJO with fixed field order, or a String) instead of a Map","Use KV<K,V> with atomic key/value coders rather than a Map, ensuring keyCoder/valueCoder are themselves deterministic"],"exampleFix":"// before\n.apply(GroupByKey.create()) // MapCoder<...> key -> NonDeterministicException\n// after\nMapCoder<MyKey, MyVal> c = MapCoder.of(OrderedCoder.of(keyCoder), valueCoder);\nc.verifyDeterministic(); // only if key/value coders deterministic and map iteration ordered","handlingStrategy":"try-catch","validationCode":"try { mapCoder.verifyDeterministic(); } catch (NonDeterministicException e) { /* choose ordered/deterministic coder */ }","typeGuard":"null","tryCatchPattern":"try { coder.verifyDeterministic(); } catch (NonDeterministicException e) { log.warn(\"using deterministic fallback coder\", e); }","preventionTips":["Check verifyDeterministic() during unit tests for any coder used as a key","Prefer KV with atomic deterministic coders over Map keys","Use ordered collections (sorted maps/lists) when grouping"],"tags":["java","beam","coders","determinism"],"backgroundTag":"unsupported-operation","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}