How Do You Override equals and hashCode Correctly?

The recipe is short and worth being able to recite without hesitating. In equals: check reference equality first, check the type second, then compare the fields that make up the identity. In hashCode: derive the value from the same fields.

Reference equality first is an optimisation and also correct — an object always equals itself. The type check is the one with a subtlety: use getClass() when the class is final, and instanceof when it is not, because a subclass that overrides equals with instanceof would break the symmetry of a getClass-based equals. Comparing the fields should use Objects.equals for reference fields, since that handles nulls on both sides.

import java.util.Objects;

public class Main {
    public static void main(String[] args) {
        System.out.println("same values  : " + new Point(1, 2).equals(new Point(1, 2)));
        System.out.println("diff values  : " + new Point(1, 2).equals(new Point(1, 3)));
        System.out.println("same hash    : " + (new Point(1, 2).hashCode() == new Point(1, 2).hashCode()));
        System.out.println("null field   : " + new Point(1, 2).equals(new Point(1, 2)));
    }
}

final class Point {
    private final int x;
    private final int 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 == null || getClass() != o.getClass()) {
            return false;
        }
        Point other = (Point) o;
        return x == other.x && y == other.y;
    }

    @Override
    public int hashCode() {
        return Objects.hash(x, y);
    }
}

The output shows the three properties the contract requires: equal values compare equal, different values do not, and equal values produce the same hash code.

Two more things worth saying. The hash code should be stable — it must not change while the object is in a hash-based collection, because the entry is filed under the old hash and becomes unreachable. And a good hash code spreads the values out, because the map uses it to pick the bucket; returning a constant works correctly but degenerates every lookup into a linear scan.

Because the two methods answer different questions and the hash-based collections need both to agree. The hash code says which bucket the key belongs in; equals says is this the same key. The contract requires that equal objects have equal hash codes, so that two equal keys always end up in the same bucket and the equals comparison can actually happen.

Override equals but not hashCode, and the default identity hash code is used. Two objects that equals says are equal have different hash codes, so they land in different buckets and a lookup with one of them never finds the other. The visible symptom is a HashSet that contains what looks like duplicates, and a HashMap where putting a key and then getting it with an equal-but-different key returns null.

Override hashCode but not equals, and you get the opposite problem. The hash codes match, so the objects do land in the same bucket, but the equals comparison says they are different because the default implementation compares identity. The result is that the collection treats two objects that you consider the same as two distinct entries, and a lookup with an equal key misses.

Neither failure is loud. The code compiles, the tests pass on small data with literal keys, and the bug appears the first time the value comes from a database or a request. That is why the rule is simply: override both, or neither.

You have to decide which fields are part of the object's identity, and only those may take part in equals and hashCode. The other fields are attributes, and including them in equals means the object's equality changes over its life — which is exactly what breaks hash-based collections.

The failure is precise. A map entry is filed under the key's hash code at the time it was inserted. If a field that contributes to hashCode is later changed, the lookup computes the new hash, looks in a different bucket, and does not find the entry. The entry is still there — the size still counts it — but it is unreachable except by iterating the whole map and removing it directly.

import java.util.HashSet;
import java.util.Objects;
import java.util.Set;

public class Main {
    public static void main(String[] args) {
        MutableKey key = new MutableKey("id", 1);
        Set<MutableKey> set = new HashSet<>();
        set.add(key);
        System.out.println("size before : " + set.size());

        // Changing an identity field breaks the hash contract.
        key.setVersion(2);
        System.out.println("contains    : " + set.contains(key));
        System.out.println("size after  : " + set.size());

        // The fix: keep the identity fields immutable.
        Set<ImmutableKey> good = new HashSet<>();
        good.add(new ImmutableKey("id", 1));
        System.out.println("immutable contains : " + good.contains(new ImmutableKey("id", 1)));
    }
}

class MutableKey {
    private final String id;
    private int version;

    MutableKey(String id, int version) {
        this.id = id;
        this.version = version;
    }

    void setVersion(int version) {
        this.version = version;
    }

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

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

class ImmutableKey {
    private final String id;
    private final int version;

    ImmutableKey(String id, int version) {
        this.id = id;
        this.version = version;
    }

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

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

The output shows the exact failure. The set still reports one entry, but the contains check now returns false, because the key's hash code changed and the lookup went to a different bucket. The immutable version of the same class behaves correctly.

The three ways to fix it. Make the identity fields final, so they cannot change. Or exclude the mutable field from both equals and hashCode, so the identity is defined only by the stable parts — which means two objects with different values of that field are considered equal, and you need to be sure that is the semantics you want. Or, if the mutable field really is part of the identity, remove the object from the collection before mutating it and re-add it afterwards.