How does HashMap handle null keys/values, what is its iteration order, and why is it not thread-safe?
answer
- One null key (bucket 0); many null values allowed
- get()==null is ambiguous -> use containsKey()
- Iteration order unspecified + changes after resize
- Not thread-safe: CME, lost updates, possible hang
- Use ConcurrentHashMap (bans nulls) / LinkedHashMap / TreeMap
basics
~20 sHashMap allows one null key (in bucket 0) and any number of null values. Its iteration order is unspecified and can change after a resize. Concurrent structural modification can corrupt it or hang a thread, so use ConcurrentHashMap or external locking.
solid answer
~50 sHashMap permits one null key, mapped to bucket index 0 (hash of null is 0), and unlimited null values. Because a null value is allowed, get() returning null is ambiguous - it could mean 'absent' or 'present with null value' - so use containsKey() to distinguish. Iteration order is unspecified and not stable: it depends on the hash spread and bucket layout, and a resize re-buckets entries and can change the order. If you need order use LinkedHashMap (insertion/access order) or TreeMap (sorted). HashMap is not synchronized; concurrent structural modification by multiple threads can lose updates, throw ConcurrentModificationException via fail-fast iterators, or, even since Java 8, leave a thread in an infinite loop. For concurrency, prefer ConcurrentHashMap (which, unlike HashMap, forbids null keys and values). Structurally modifying a HashMap during single-threaded iteration can also throw ConcurrentModificationException unless you use the iterator's own remove(); changing an existing key's value is not structural.
code
java · 23 linesimport java.util.HashMap;
import java.util.Map;
public class NullsAndRemoval {
public static void main(String[] args) {
Map<String, String> m = new HashMap<>();
m.put(null, "nullKeyOk"); // one null key allowed (bucket 0)
m.put("a", null); // null values allowed
String v = m.get("a"); // returns null...
boolean present = m.containsKey("a"); // true: present with null, not absent
System.out.println(v + " " + present); // null true
// Removing during iteration safely:
for (var it = m.entrySet().iterator(); it.hasNext(); ) {
var e = it.next();
if (e.getValue() == null) {
it.remove(); // m.remove(...) here risks ConcurrentModificationException
}
}
System.out.println(m); // {null=nullKeyOk}
}
}
go deeper
Knows one null key and many null values are allowed and that HashMap is not thread-safe.
Explains the get()/null ambiguity, that order is unspecified and changes on resize, and names ConcurrentHashMap/LinkedHashMap/TreeMap as alternatives.
Details fail-fast iterators/modCount, the pre-Java-8 resize cycle, the hangs still possible in tree bins, and why ConcurrentHashMap bans nulls.
Advises on concurrency strategy (CHM vs synchronizedMap vs immutable maps), the ordering contract as an API guarantee, and migration pitfalls when code accidentally depends on iteration order.
## Null handling - **Null key**: HashMap allows **one** null key. Its `hash()` function returns `0` for null, so the null key always lives in **bucket 0**. A second put with a null key overwrites the first (keys are unique). - **Null values**: HashMap allows **any number** of null values - several keys can map to null. - **The get() ambiguity**: since values may be null, `map.get(k) == null` does not tell you whether `k` is absent or present-with-null-value. Use `map.containsKey(k)` to distinguish. (`ConcurrentHashMap` bans nulls entirely, so there a null from `get` can only mean absent.) ## Iteration order HashMap makes **no guarantee** about iteration order, and the order is **not stable over time**: - Entries are visited bucket by bucket, and within a bucket along its chain. Which bucket a key lands in depends on its spread hash and the current capacity. - A **resize** moves entries into a larger table (the low/high split), changing which bucket many entries occupy - so iteration order can differ before and after a resize, even with the same keys. Never rely on, log, or test against HashMap order. If you need a defined order: - **LinkedHashMap** maintains a doubly-linked list across entries for **insertion order** (or access order if configured). - **TreeMap** keeps keys **sorted** by natural order or a Comparator. ## Why HashMap is not thread-safe HashMap has **no internal synchronization**. With concurrent access where at least one thread structurally modifies it (put/remove/resize): - **Lost updates / corruption**: two threads resizing or inserting simultaneously can leave the table in an inconsistent state. - **Infinite loop**: before Java 8 the resize used head-insertion and could create a **cycle** in a bucket's linked list under a race, making a later get() spin forever and peg a CPU. Java 8's tail-insertion split removed that specific cycle, not the hazard: on JDK 27, eight threads sharing a HashMap of colliding keys, so that tree bins formed, left threads spinning in `TreeNode.putTreeVal` and making no progress. - **Fail-fast iterators**: HashMap's iterators track a `modCount`; if the map is structurally modified during iteration (by another thread, or by the same thread not using `iterator.remove()`), the next `next()` throws **ConcurrentModificationException** (CME). This is a best-effort bug detector, not a guarantee. ## The safe alternatives - **ConcurrentHashMap**: built for concurrency - retrievals do not lock, and updates use a CAS on an empty bin or lock a single bin. It **forbids null keys and null values** (so `get()==null` unambiguously means absent). Prefer it for shared mutable maps. - **Collections.synchronizedMap(new HashMap<>())**: wraps every method in a single lock - simple but coarse; iteration still needs manual external synchronization and is fail-fast. ## ConcurrentModificationException even single-threaded Even in one thread, **structurally** modifying a HashMap while iterating its keySet/entrySet (other than via the iterator's own `remove()`) makes the iterator's next `next()` throw CME. Some changes slip through on JDK 27: changing the value of an existing key is not structural, and a structural change during the last step (a removal, a new key, even `clear()`) goes unnoticed because `next()` is not called again. Depend on neither. To remove during iteration, use `iterator.remove()` or `map.entrySet().removeIf(...)`.
- How do you tell whether a key is absent or mapped to null?Use containsKey(key). get(key) returns null in both cases (absent, or present with a null value), so it cannot distinguish them.
- What ordered alternatives exist if you need predictable iteration?LinkedHashMap for insertion order (or access order for LRU-style use) and TreeMap for keys sorted by natural ordering or a Comparator.
- Claiming HashMap preserves insertion order (that is LinkedHashMap)
- Saying HashMap allows no null keys (it allows exactly one)
- Thinking get() returning null always means the key is absent
- Calling HashMap thread-safe or 'safe for reads while another thread writes'
- Saying ConcurrentHashMap allows null keys/values (it forbids both)
Assumes JDK 27; the null rules, iteration contract and fail-fast behaviour read the same at JDK 25. The head-link cycle belongs to the resize before Java 8; a hang under races does not: JDK 27 can still hang.
context
- HashMap (Java SE 27 & JDK 27)docs.oracle.com
- ConcurrentHashMap (Java SE 27 & JDK 27)docs.oracle.com