What is the contract between hashCode() and equals()?

The Answer

Say this in the room. 45 seconds.

• The contract is one-directional: if a.equals(b), then a.hashCode() == b.hashCode().
• The converse is not required. Two unequal objects may share a hash code. That's a collision, and collisions are normal.
• So a hashCode() that returns a constant is legal. It's slow, not wrong.
• hashCode() must also be consistent: the same object returns the same value while nothing about it changes.
• Override one and you must override the other. HashMap, HashSet and Objects.hash all assume it holds.
• Break it and nothing throws. You just stop finding your own entries.

Understand It

The rule that only runs one way

Written out, the whole contract is three sentences:

The middle row is the one people get wrong in interviews. They reach for "different objects must have different hash codes", which is not merely unrequired — it's impossible. hashCode() returns an int: about 4.3 billion values. There are more than 4.3 billion possible Strings. Collisions are guaranteed by counting, not by bad luck.

Two-character strings show it immediately:

System.out.println("\"Aa\".hashCode() = " + "Aa".hashCode());
System.out.println("\"BB\".hashCode() = " + "BB".hashCode());
System.out.println("but equal? " + "Aa".equals("BB"));

"Aa".hashCode() = 2112
"BB".hashCode() = 2112
but equal? false

Same hash, not equal, and String is a JDK class whose hashCode() nobody would call broken. equals() is what decides identity. The hash only decides which bucket to look in.

Why a constant hash code is legal

If you accept that collisions are permitted, a hashCode() that returns 1 for everything is just the extreme case — every object collides with every other. It satisfies the contract, so the collection still behaves correctly:

Map<Const, String> m = new HashMap<>();
for (int i = 0; i < 1000; i++) m.put(new Const(i), "v" + i);

System.out.println("size          = " + m.size());
System.out.println("get(new Const(500)) = " + m.get(new Const(500)));

size          = 1000
get(new Const(500)) = v500

A thousand entries, all in one bucket, every lookup still correct. What you lost is speed, not correctness — that's O(log n) per lookup after the bin treeifies instead of O(1). Correctness and performance are separate axes here, and saying so is what distinguishes a real answer from a memorised one.

Breaking it in the direction that matters

Now the direction that does damage. Override equals() and leave hashCode() inherited from Object, which returns an identity-based value:

Map<Broken, String> m = new HashMap<>();
m.put(new Broken(1), "first");

System.out.println("equals says the same:  " + new Broken(1).equals(new Broken(1)));
System.out.println("hashCodes match:       "
    + (new Broken(1).hashCode() == new Broken(1).hashCode()));
System.out.println("get with an equal key: " + m.get(new Broken(1)));
System.out.println("containsKey:           " + m.containsKey(new Broken(1)));
System.out.println("size:                  " + m.size());

equals says the same:  true
hashCodes match:       false
get with an equal key: null
containsKey:           false
size:                  1

The entry is in the map. size() counts it. Two objects that equals() calls identical, and the map finds neither from the other — because they hash to different buckets, so equals() is never even reached. No exception, no warning. This is the single most common cause of "my HashSet has duplicates in it".

What a correct pair looks like

Since Java 7 there is no reason to hand-roll either method:

@Override
public boolean equals(Object o) {
    if (this == o) return true;
    if (!(o instanceof Order other)) return false;
    return id == other.id && Objects.equals(region, other.region);
}

@Override
public int hashCode() {
    return Objects.hash(id, region);
}

Three things to notice. instanceof with a pattern variable handles the null case for free — null instanceof Order is false, so no explicit null check. The two methods must read the same fields; that agreement is the contract, and it's why they belong next to each other in the file. And Objects.hash boxes its arguments into an array, so on a genuinely hot path a hand-written 31 * id + region.hashCode() still wins — measure before you care.

Records make the whole problem go away

A record generates both methods from its components, so they cannot drift:

System.out.println(new Point(1, 2).equals(new Point(1, 2)));
System.out.println(new Point(1, 2).hashCode() == new Point(1, 2).hashCode());

true
true

Add a field to a record and both methods update themselves. Add a field to a hand-written class and you have to remember two places. That's the real argument for records as key types, and it's a better answer than "less boilerplate".

The stability rule, and where it bites

The third rule — a stable hash while the object is unchanged — is the one people never quote and interviewers love. A mutable field that hashCode() reads is a live grenade: mutate it after insertion and the entry stays in the bucket chosen by the old hash, permanently unreachable.

Which is why key types should be immutable. Not "should ideally be" — the contract cannot be honoured by a mutable key that anyone actually mutates. That failure is the Challenge exercise on How does HashMap work internally?.

Interviewer's Next Move

The question after the question. This is what the round is actually testing.

1. "Must unequal objects have different hash codes?" No. Only the forward direction is required. int has 4.3 billion values and String alone has more possible instances than that, so collisions are unavoidable by counting. "Aa" and "BB" both hash to 2112.

2. "What breaks if hashCode() returns a constant?" Nothing breaks. It's contract-legal and stays correct. Every key lands in one bucket, so lookups go O(n), then O(log n) once the bin treeifies at 8 nodes with a table of 64+. Correctness and performance are separate concerns.

3. "I overrode equals() and not hashCode(). What happens?" Nothing at compile time and nothing at runtime — that's the danger. Equal objects hash to different buckets, so get() and containsKey() return nothing while size() still counts the entry. It's the usual cause of apparent duplicates in a HashSet.

4. "Does equals() have to be symmetric? What about across a subclass?" Yes, and that's exactly where it breaks. If Sub extends Base adds a field and its equals() accepts a Base, you can get base.equals(sub) true while sub.equals(base) is false. instanceof is lenient and asymmetric; getClass() != o.getClass() is strict and symmetric but then no subclass instance ever equals a base instance. There is no answer that satisfies everyone, which is why record types are final.

5. "Why must a key be immutable?" Because the third rule requires the hash to stay stable while the object is in the map. Mutate a hash-bearing field and the entry sits in the bucket for its old hash: unreachable by get(), unremovable by remove(), still counted by size(), still holding memory.

6. "Is Objects.hash() the right default?" Yes for readability, and it's what records generate. It allocates a varargs array and boxes primitives on every call, so on a proven hot path a hand-written accumulation avoids that. Profile before optimising.

Code traps

Trap A — predict before you run:

Set<StringBuilder> set = new HashSet<>();
StringBuilder sb = new StringBuilder("a");
set.add(sb);
sb.append("b");
System.out.println(set.contains(sb));
System.out.println(set.size());

Trap B:

Map<Integer, String> m = new HashMap<>();
m.put(127, "a");
m.put(128, "b");
System.out.println(m.get(127) + " " + m.get(128));
Integer x = 127, y = 127, p = 128, q = 128;
System.out.println((x == y) + " " + (p == q));

Common wrong answers

Check Yourself

Q1. a.hashCode() == b.hashCode() is true. What, if anything, do you know about a.equals(b)?

Q2. A class overrides hashCode() but not equals(). Can it be used as a HashMap key?

Q3. Why is record a better key type than a hand-written class with the same fields?

Practice