skip to content

How does HashMap handle null keys/values, what is its iteration order, and why is it not thread-safe?

level: middleimportance: must knowfreq 70%

answer

  1. One null key (bucket 0); many null values allowed
  2. get()==null is ambiguous -> use containsKey()
  3. Iteration order unspecified + changes after resize
  4. Not thread-safe: CME, lost updates, possible hang
  5. Use ConcurrentHashMap (bans nulls) / LinkedHashMap / TreeMap

basics

~20 s

HashMap 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 s

HashMap 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 lines
java
import 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

for a junior

Knows one null key and many null values are allowed and that HashMap is not thread-safe.

for a middle

Explains the get()/null ambiguity, that order is unspecified and changes on resize, and names ConcurrentHashMap/LinkedHashMap/TreeMap as alternatives.

for a senior

Details fail-fast iterators/modCount, the pre-Java-8 resize cycle, the hangs still possible in tree bins, and why ConcurrentHashMap bans nulls.

for a principal

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