equals() and hashCode() in Java: The Contract, Real Bugs and How Records Change It

Tested against: JDK 25.0.5+8 (Temurin LTS), JUnit Jupiter 5.11.0, Maven 3.9.11. All 13 tests pass (output/08-tests.txt). The JPA section is a plain-Java simulation with no Hibernate on the classpath, and says so where it matters.

What equals() and hashCode() are each for

Override only equals() and the set holds duplicates

static final class Broken {
    final String isbn;
    Broken(String isbn) { this.isbn = isbn; }
    @Override public boolean equals(Object o) { return o instanceof Broken b && isbn.equals(b.isbn); }
    // hashCode() NOT overridden: Object.hashCode() is identity-based
}

== equals() without hashCode() ==
a.equals(b)                 = true
a.hashCode() == b.hashCode() = false
HashSet size after adding a then b = 2
HashSet.contains(new equal key)    = false
HashMap.get(equal key)             = null

== with hashCode() ==
HashSet size after adding c then d = 1
HashSet.contains(new equal key)    = true

The fingerprint of this bug: “it works in my unit test, fails in production.” The default hashCode() comes from the object’s identity, so a lookup with a different instance only succeeds if two identity hashes happen to land in the same bucket. The run above is not a coincidence of seeds; it is what you should expect almost every time.

static final class Constant {
    static long equalsCalls;
    final int id;
    Constant(int id) { this.id = id; }
    @Override public boolean equals(Object o) { equalsCalls++; return o instanceof Constant c && id == c.id; }
    @Override public int hashCode() { return 42; }
}

== a legal but useless hashCode(): return 42 ==
keys                                  = 2000
equals() calls for 2000 gets, constant hash = 2002999
equals() calls for 2000 gets, good hash     = 2000

The five rules of the equals() contract

static class Point {
    final int x, y;
    Point(int x, int y) { this.x = x; this.y = y; }
    @Override public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Point p)) return false;
        return x == p.x && y == p.y;
    }
    @Override public int hashCode() { return Objects.hash(x, y); }
}

Subclasses are where the contract breaks

static class ColorPoint extends Point {
    final String color;
    ColorPoint(int x, int y, String color) { super(x, y); this.color = color; }
    @Override public boolean equals(Object o) {
        if (!(o instanceof ColorPoint c)) return false;   // a plain Point is never equal
        return super.equals(o) && color.equals(c.color);
    }
    @Override public int hashCode() { return Objects.hash(super.hashCode(), color); }
}

== Symmetry broken by instanceof + extra field ==
plain.equals(red) = true
red.equals(plain) = false
List.of(plain).contains(red) = false
List.of(red).contains(plain) = true

== Transitivity broken by the lenient fix ==
r.equals(plain) = true
plain.equals(b) = true
r.equals(b)     = false

There is no way to add a field to an instantiable class and keep equals() correct across the hierarchy if the subclass’s equals() uses the new field and the two types can meet. The options that work are: make the class final (or a record), use composition (a ColorPoint that has a Point instead of being one), or compare with getClass(), which gives up substitutability.

date.equals(ts) = true
ts.equals(date) = false
date.getTime() == ts.getTime() = true

Mutable keys: the entry you can see but cannot find

static final class Account {
    String owner;
    Account(String owner) { this.owner = owner; }
    @Override public boolean equals(Object o) { return o instanceof Account a && owner.equals(a.owner); }
    @Override public int hashCode() { return owner.hashCode(); }
    @Override public String toString() { return "Account(" + owner + ")"; }
}

before: get = 100, contains = true

after acc.owner = "ankur":
map.get(acc)             = null
set.contains(acc)        = false
map.containsKey(acc)     = false
map.size()               = 1
iteration still sees it  = [Account(ankur)]
map.remove(acc)          = null
map.size() after remove  = 1

set.add(acc) again -> size = 2 [Account(ankur), Account(ankur)]  (one object, two entries)

immutable key: map.get("asha") = 1

Rule of thumb: never mutate a field that feeds hashCode() while the object is inside a hash collection. Better, make key classes immutable, so the question never comes up.

Records generate both methods for you

record Book(String isbn, String title) {}
record WithArray(String name, int[] values) {}
record WithList(String name, List<Integer> values) {}
record WithDouble(double d) {}

== generated equals/hashCode ==
a.equals(b)                = true
a.hashCode() == b.hashCode() = true
new HashSet of both, size  = 1
a == b                     = false

== array component: reference equality ==
w1.equals(w2) = false
same array shared: true

== doubles compare with Double.compare semantics ==
NaN record equals NaN record = true
Double.NaN == Double.NaN     = false
0.0 record equals -0.0 record = false
0.0 == -0.0                   = true

== mutable List component: equals works, hashCode can change ==
hashCode before = 4714, after list.add(3) = 34537
record in HashSet, list mutated -> contains = false

record Tagged(String isbn, String title) {   // custom equals: identity is the ISBN only
    @Override public boolean equals(Object o) { return o instanceof Tagged t && isbn.equals(t.isbn); }
    @Override public int hashCode() { return isbn.hashCode(); }
}

== overriding equals in a record ==
t1.equals(t2) = true
toString still shows both fields: Tagged[isbn=1, title=Effective Java 3e]

The JPA entity trap: an id that appears after the object is in a set

static final class IdEntity {
    Long id; final String name;
    IdEntity(String name) { this.name = name; }
    void save() { if (id == null) id = ++sequence; }   // stands in for persist()
    @Override public boolean equals(Object o) { return o instanceof IdEntity e && Objects.equals(id, e.id); }
    @Override public int hashCode() { return Objects.hashCode(id); }
}

== id-based equals/hashCode, id assigned on save ==
two unsaved entities equal?  true  (both ids null)
set size after adding two different unsaved entities = 1
add, then save(): set.contains(c) = false

static final class NaturalKeyEntity {
    Long id; final String email;
    NaturalKeyEntity(String email) { this.email = email; }
    void save() { if (id == null) id = ++sequence; }
    @Override public boolean equals(Object o) { return o instanceof NaturalKeyEntity e && email.equals(e.email); }
    @Override public int hashCode() { return email.hashCode(); }
}

== natural key, immutable ==
add, then save(): set.contains(e) = true

== constant hashCode ==
add, then save(): set.contains(d) = true

Writing hashCode(): what the JDK computes, and what to use

== what the JDK uses ==
"hello".hashCode()            = 99162322
31*h + c over "hello"          = 99162322
List.of(1,2,3).hashCode()      = 30817
Arrays.hashCode({1,2,3})       = 30817
Objects.hash(1,2,3)            = 30817
Set.of(1,2,3).hashCode()       = 6  (sum of elements)
Map.of(1,2).hashCode()         = 3  (key^value per entry, summed)

== equal hashCodes do not mean equal objects ==
"Aa".hashCode() = 2112, "BB".hashCode() = 2112, equal strings? false

== Objects.hash(...) traps ==
Objects.hash("a") vs "a".hashCode() = 128 vs 97
Objects.hash(1, 2) == Objects.hash(2, 1) ? false
Objects.hash() (no args)       = 1
Objects.hash((Object) null)    = 31

== Arrays as fields ==
x.equals(y) = false, Arrays.equals = true
x.hashCode() == y.hashCode() ? false
Arrays.hashCode equal ? true

Checklist, and when to skip all this

Should you hand-write these at all? Usually no. Use a record for value types and map keys, make the component types immutable, and you get a correct pair with nothing to maintain. Hand-write them only for classes with identity that is not “all fields” (entities, caches keyed by an ID, objects wrapping resources). When you do: compare and hash the same fields; keep those fields immutable or the object out of hash collections while they change; make the class final or document the subclass rule; and write a test that adds the object to a HashSet, mutates nothing, and finds it again, which is the cheapest bug catcher in this whole post.

Further reading

• Companion code: equals-hashcode module in java-core-examples, with every output file and 13 contract tests.
• Related on this site: HashMap vs ConcurrentHashMap, Comparator and Comparable, Immutable Collections in Java, Top 40 Hibernate and JPA interview questions.
• Object (Java SE 25 Javadoc): the equals and hashCode contract.
• Record (Java SE 25 Javadoc): how generated equals and hashCode compare components.
• java.sql.Timestamp: the note on symmetry with java.util.Date.