What happens if you mutate a field used in hashCode() after an object is already a key in a HashMap, and how do you avoid it?

## Background: how a key's bucket is fixed When you call `map.put(key, value)`, HashMap calls `key.hashCode()` **once, at that moment**, reduces it to a bucket index `(n-1) & hash`, and stores the entry in that bucket. It also caches the hash inside the entry. Crucially, HashMap **does not watch the key for changes** — there is no callback when a field mutates. The entry stays exactly where it was filed. ## The failure: a moving key in a static filing system Suppose a key's `hashCode()` depends on a field `name`, and you do: ```java Map<User, String> map = new HashMap<>(); User u = new User("alice"); map.put(u, "data"); // filed in bucket for hash("alice") u.setName("bob"); // hashCode() now reflects "bob" String v = map.get(u); // probes bucket for hash("bob") -> MISS -> null ``` - `put` filed the entry in the **"alice" bucket**. - Mutation changed `u`'s hash to the **"bob" hash**, but the entry is still physically in the alice bucket. - `get(u)` computes the **bob** hash, goes to the **bob bucket**, finds nothing, returns `null`. The entry is now **orphaned**: it still lives in the alice bucket (still counts toward `size()`, still shows up in iteration), but **no key-based operation can reach it** — not `get`, not `containsKey`, not `remove(u)`. You also can't `put` a "correct" replacement cleanly because the duplicate-detection probe also lands in the bob bucket. The same logic ruins `HashSet` membership, and breaks `TreeMap`/`TreeSet` differently (those rely on `compareTo`, so mutating a sort field corrupts the tree ordering instead). ## Why this is subtle - It's **silent** — no exception, just `null` and a phantom entry. - It can pass tests if mutation never happens in the test path, then fail in production when a key is updated in place. - A particularly nasty variant: using a **mutable collection** (e.g. an `ArrayList`) as a HashMap key. `List.hashCode()` is defined from its elements, so adding/removing an element silently moves the key — same orphaning. ## How to avoid it 1. **Make hash-participating fields `final` / the key type immutable.** If the fields used in `hashCode()` can't change, the bucket can't go stale. Value types, **records**, and other immutable classes are the natural fix and the standard advice. 2. **Use stable, immutable keys.** Prefer `String`, boxed primitives, enums, or your own immutable value objects as map keys. 3. **If a key truly must change, remove-then-reinsert:** `map.remove(key); /* mutate */ map.put(key, value);` so the entry is re-filed under the new hash. (Awkward and error-prone — a sign you want an immutable key instead.) 4. **Don't use mutable collections as keys** while you still mutate them. ## Relationship to the interdependence rule This is the *dynamic* cousin of the equals/hashCode contract. The static contract says "equal objects must hash equally"; the **consistency** clause of the equals contract also says equals/hashCode must return the same results **as long as the objects don't change in an equals-relevant way**. Mutating a hash field breaks that temporal consistency: the *same object* presents two different hashes over its lifetime, which the snapshot-based bucket placement cannot tolerate. Immutability is the clean guarantee that the snapshot never goes stale.