skip to content

What is the equals/hashCode contract, and why does violating it break a HashSet?

level: middleimportance: must knowfreq 85%

answer

  1. equal objects => equal hashCodes (one direction only)
  2. Override equals AND hashCode together, same fields
  3. Forget hashCode => duplicates in HashSet
  4. Mutate hash field after insert => lost element
  5. Use immutable fields / records / Objects.hash

basics

~10 s

If two objects are equal by equals(), they must return the same hashCode(). If you break this, a HashSet can store duplicates or fail to find elements you put in.

solid answer

~50 s

The contract links two Object methods. equals() must be reflexive, symmetric, transitive, consistent, and x.equals(null) must be false. hashCode() must return the same int for objects that are equal by equals(), and should ideally spread unequal objects across different values. The binding rule: equal objects MUST have equal hash codes (the reverse is not required — collisions are allowed). HashSet relies on this: it locates an element's bucket by hashCode, then confirms with equals. If you override equals but not hashCode, two 'equal' objects almost always get different identity hash codes, and HashSet checks the stored hash before equals, so it never compares them and stores both — a logical duplicate. Conversely, an unstable hashCode (changing after insertion) makes contains/remove miss the element. Practically, always override equals and hashCode together, base both on the same immutable fields, and prefer Objects.equals/Objects.hash or records.

code

java · 14 lines
java
// Correct, field-based implementation
final class Money {
    private final long cents;
    private final String currency;
    Money(long cents, String currency){ this.cents = cents; this.currency = currency; }

    @Override public boolean equals(Object o){
        if (this == o) return true;
        if (!(o instanceof Money m)) return false;
        return cents == m.cents && currency.equals(m.currency);
    }
    @Override public int hashCode(){ return Objects.hash(cents, currency); }
}
// Or simply: record Money(long cents, String currency) {}  // auto equals/hashCode

go deeper

for a junior

Knows you must override equals and hashCode together and that forgetting hashCode breaks HashSet; can use a record or IDE-generated methods.

for a middle

States all five equals properties and the equal-objects-equal-hashes rule, and explains the duplicate and lost-element failures with a concrete example.

for a senior

Reasons about hash distribution quality, immutability of equality fields, symmetry pitfalls in inheritance (Liskov), and when to prefer records or Objects.hash.

for a principal

Considers domain-wide identity strategy (value vs entity equality), API contracts that depend on equality, performance of hashCode under adversarial input (hash-flooding), and migration risk when changing equals.

## Two methods that must cooperate Every Java object has two inherited methods from `Object`: - **`boolean equals(Object o)`** — "are these two objects the same *value*?" - **`int hashCode()`** — "give me an `int` fingerprint of this object." Hash-based collections (`HashSet`, `HashMap`) use **both together**, so Java defines a **contract** they must obey. ## The equals contract For non-null references, `equals` must be: - **Reflexive**: `x.equals(x)` is true. - **Symmetric**: `x.equals(y)` ⇔ `y.equals(x)`. - **Transitive**: if `x.equals(y)` and `y.equals(z)`, then `x.equals(z)`. - **Consistent**: repeated calls give the same answer if the objects don't change. - **Null-safe**: `x.equals(null)` is `false`. ## The hashCode contract - **Self-consistent**: same object, same hash within a run (unless equals-relevant state changes). - **THE key rule**: if `x.equals(y)` is true, then `x.hashCode() == y.hashCode()` **must** hold. - **One-way only**: equal hash codes do **not** imply equal objects. Two different objects sharing a hash is a *collision* — allowed and normal. - **Quality**: a good `hashCode` spreads unequal objects across many values to keep buckets small. ## Why HashSet depends on it `HashSet.add(x)` does: compute `x.hashCode()` → go to that bucket → call `equals` only on elements there whose stored hash matches. Two consequences: **Override equals but NOT hashCode** → two "equal" objects inherit `Object`'s identity hash, so their hash codes almost always differ. Usually they land in different buckets, and even in a shared bucket the stored hash does not match, so `equals` is never called. The Set then holds both — a **logical duplicate** that defeats the whole point of a Set. **Unstable hashCode** → you insert `x`, later mutate a field used by `hashCode`, then call `contains(x)`. The Set computes the new hash, which no longer matches the hash stored with the element, so `contains` returns **false** and `remove` silently fails — a "lost" element / memory leak. ## Worked failure ```java class Point { int x, y; Point(int x, int y){ this.x = x; this.y = y; } public boolean equals(Object o){ return o instanceof Point p && p.x==x && p.y==y; } // forgot hashCode() -> inherits Object's identity hash } Set<Point> s = new HashSet<>(); s.add(new Point(1,1)); s.add(new Point(1,1)); // equal by equals, but the identity hashes differ -> equals never runs s.size(); // 2 (BUG: duplicate stored) ``` Adding a matching `hashCode` (e.g. `Objects.hash(x, y)`) fixes it and `size()` becomes 1. ## How to get it right - Override `equals` and `hashCode` **together**, from the **same fields**. - Use only **immutable, equality-defining** fields so the hash never changes after insertion. - Prefer `Objects.equals(a,b)` and `Objects.hash(...)`, or let the compiler do it: a **`record`** (final since Java 16) auto-generates a correct, field-based `equals`/`hashCode`. It is only shallowly immutable, though: a mutable `List` component still changes the hash. - Don't include mutable or derived fields you don't compare in `equals`.

  • Does the contract require unequal objects to have unequal hash codes?
    No. Only equal objects must share a hash code. Unequal objects may collide on the same hash; the Set just resolves it with equals() inside the bucket. Good hashing minimizes collisions for performance, but they are never a correctness bug.
  • Why are records a good fit for Set elements?
    A record (final since Java 16) generates equals() and hashCode() from all its components and is shallowly immutable, so the contract is satisfied and, as long as the components are immutable too, the hash stays stable after insertion. A mutable List component can still change the hash.

hashCode is the aisle number in a library, equals is reading the exact title. Equal books must share an aisle, or the librarian (HashSet) walks the wrong aisle and never finds the match.

  • Saying equal hash codes imply equal objects — the implication only runs from equals to hashCode.
  • Overriding equals without hashCode (or vice versa).
  • Including mutable fields in hashCode, then mutating them after insertion.
  • Claiming collisions are a bug — they are expected and handled by equals within a bucket.
  • Forgetting the null/instanceof check in equals, causing NullPointerException or ClassCastException.

records
Java 16pre-release 14

Assumes JDK 27. The record recommendation needs Java 16 or later, where records became final after previews from 14, so it holds on 25 LTS too.

context