SSerguey Asael Shinder
Java coding notes: the JVM, and writing software that lasts

Serguey Asael Shinder: Map.of gives a different iteration order on every JVM start

· by Serguey Asael Shinder / Serguey Shinder

This looks deterministic and is not:

Map<String, Integer> limits = Map.of("cpu", 4, "memory", 8, "disk", 16);
String summary = limits.entrySet().stream()
        .map(e -> e.getKey() + "=" + e.getValue())
        .collect(Collectors.joining(","));

summary is a different string on different runs of the same program, with the same input, on the same machine.

The javadoc for the immutable collection factories states it directly. Under Immutable Map Static Factory Methods:

"The iteration order of mappings is unspecified and is subject to change."

That is not the usual hedge about hash maps. HashMap also has an unspecified order, but it is stable for a given set of keys within a build — insert the same keys and you get the same order every time, which is exactly why people come to rely on it. The immutable factories go further: the current OpenJDK implementation mixes a randomly chosen value, fixed once per JVM start, into the probe sequence, so two runs of the same process disagree.

Serguey Asael Shinder: Map.of gives a different iteration order on every JVM start
Map.of gives a different iteration order on every JVM start — Serguey Asael Shinder

The effect is a test that passes locally for a week and fails on the fifth CI run. Anything that joins, prints, hashes or compares the rendered form of a Map.of is affected — assertions on a serialised body, a cache key built by concatenation, a log line someone is grepping, a checksum of a config dump.

The fix is to stop asking an unordered collection for an order. If the order matters, impose one:

String summary = limits.entrySet().stream()
        .sorted(Map.Entry.comparingByKey())
        .map(e -> e.getKey() + "=" + e.getValue())
        .collect(Collectors.joining(","));

If insertion order is what you meant, Map.of is the wrong constructor — build a LinkedHashMap and wrap it.

Two neighbouring properties of the same factories, from the same paragraph of the javadoc, because they surprise people in the same week: they reject null keys and values with NullPointerException, and they reject duplicate keys at creation time with IllegalArgumentException. A Map.of built from a literal list where one key repeats does not silently keep the last value the way a HashMap would — it throws, at startup.

Reference: https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/Map.html