java.lang.IllegalArgumentException: Comparison method violates its general contract!

Q: Build comparators from Comparator.comparing chains

When to use: Use this whenever key fields exist and natural ordering per key is sound.. Composed comparators delegate to well-tested per-type comparisons, making antisymmetry and transitivity structural rather than hand-maintained.

Q: Never subtract inside compare - use Integer.compare

When to use: Use this if migrating legacy (a, b) -> a.x - b.x lambdas.. Subtraction overflows near Integer.MIN_VALUE/MAX_VALUE and flips the sign, producing exactly the inconsistency TimSort detects; Integer.compare is overflow-proof.

Q: Handle nulls and special values explicitly

When to use: Use this if collections can contain null elements or NaN values.. nullsFirst/nullsLast wrap any comparator safely, and Double.compare/Float.compare define a deterministic total order for NaN instead of letting it poison transitivity.

Q: Make comparators pure and deterministic

When to use: Use this if the comparator reads anything that changes between calls.. No Math.random(), no counters, no fields mutated while sorting; extract immutable keys first so every pair compares identically however often asked.

Q: Add a total-order tie-breaker

When to use: Use this if primary keys collide often (equal comparisons).. A unique final key such as id makes the ordering a strict total order, removing ambiguity TimSort could observe as inconsistency across cached merges.

🔴 The Error You're Seeing

Confirm this matches your console output. If it does, you're in the right place.

ERROR LOG

[DOC-DERIVED] Wording stable since JDK 7 TimSort enforcement; frames vary with array size/shape:
java.lang.IllegalArgumentException: Comparison method violates its general contract!
	at java.base/java.util.TimSort.mergeLo(TimSort.java)
	at java.base/java.util.TimSort.mergeAt(TimSort.java)
	at java.base/java.util.Arrays.sort(Arrays.java)

⚡ Quick Fix Works 80% of the time

Replace hand-written compare logic with Comparator.comparing chains that are consistent by construction.

list.sort(Comparator.comparing(Employee::dept)
                 .thenComparing(Employee::salary)
                 .thenComparing(Employee::id));

🧠 Why this Happens

Tap to expand the deep technical explanation

TimSort caches earlier comparison results and merges pre-sorted runs using them. During a merge it re-checks consistency: if compare(a,b) contradicts what it recorded - non-transitive chains, or compare(a,b) not being the negation of compare(b,a) - continuing would corrupt ordering, so it throws instead. The classic silent culprit is subtraction: (int)(a.x - b.x) overflows int and flips signs on large magnitudes. NaN ordering and comparators reading mutable or random state cause the same abort. Small arrays take the binary-insertion path which never detects inconsistency, explaining why tests pass and production fails.

The HITEC City Parking Spot Analogy:

A knockout bracket where the referee sometimes says A beat B and sometimes B beat A: seeding becomes impossible and the tournament stops.

🔁 How to Reproduce Confirm this is your error

Sort ~100_000 records with a transitivity-breaking comparator, e.g. comparing on Math.random() or overflowing subtraction. Small test arrays usually do NOT trigger it.

🛠️ Solutions (5 Ways to Fix)

Solution 1✓ Most common cause

Build comparators from Comparator.comparing chains

👉 Use this whenever key fields exist and natural ordering per key is sound.

Composed comparators delegate to well-tested per-type comparisons, making antisymmetry and transitivity structural rather than hand-maintained.

Comparator<Employee> byDeptThenSalary =
    Comparator.comparing((Employee e) -> e.dept())
              .thenComparingDouble(Employee::salary);

Solution 2

Never subtract inside compare - use Integer.compare

👉 Use this if migrating legacy (a, b) -> a.x - b.x lambdas.

Subtraction overflows near Integer.MIN_VALUE/MAX_VALUE and flips the sign, producing exactly the inconsistency TimSort detects; Integer.compare is overflow-proof.

// BROKEN: list.sort((a, b) -> a.balance() - b.balance());
list.sort((a, b) -> Integer.compare(a.balance(), b.balance()));

Solution 3

Handle nulls and special values explicitly

👉 Use this if collections can contain null elements or NaN values.

nullsFirst/nullsLast wrap any comparator safely, and Double.compare/Float.compare define a deterministic total order for NaN instead of letting it poison transitivity.

list.sort(Comparator.nullsLast(Comparator.comparing(User::name)));
list.sort(Comparator.comparingDouble(Sensor::reading)); // uses Double.compare internally

Solution 4

Make comparators pure and deterministic

👉 Use this if the comparator reads anything that changes between calls.

No Math.random(), no counters, no fields mutated while sorting; extract immutable keys first so every pair compares identically however often asked.

// Snapshot keys before sorting if source data mutates
var snapshot = list.stream()
    .map(e -> Map.entry(e.id(), e.score()))
    .collect(Collectors.toList());

Solution 5

Add a total-order tie-breaker

👉 Use this if primary keys collide often (equal comparisons).

A unique final key such as id makes the ordering a strict total order, removing ambiguity TimSort could observe as inconsistency across cached merges.

.thenComparing(Employee::id) // unique tie-breaker

📋 Version Notes

Java 6 and earlier

Legacy merge sort never validated comparator consistency - silent wrong orders were possible.

Java 7+

TimSort enforcement begins; this exact message introduced.

Java 8+

Comparator.comparing/nullsFirst family added, making correct-by-construction chains idiomatic.

🛡️ How to Prevent This Next Time

Write object sorting only through Comparator.comparing compositions; reserve hand-written lambdas for primitive wrappers around Integer.compare-style helpers.