diff --git a/core/src/main/java/ai/timefold/solver/core/impl/domain/variable/listener/support/violation/VariableId.java b/core/src/main/java/ai/timefold/solver/core/impl/domain/variable/listener/support/violation/VariableId.java
index 6817d81e10..53d4832770 100644
--- a/core/src/main/java/ai/timefold/solver/core/impl/domain/variable/listener/support/violation/VariableId.java
+++ b/core/src/main/java/ai/timefold/solver/core/impl/domain/variable/listener/support/violation/VariableId.java
@@ -6,7 +6,11 @@
  * A {@link VariableId} is an entity/variable of a given solution.
  * {@link VariableId} cannot be compared across different solution instances,
  * since variableDescriptor and entity are compared by reference equality.
- *
+ * <p>
+ * Note: The entity is compared using {@link Object#equals(Object)} and {@link Object#hashCode()},
+ * so it's important that the planning entity class properly overrides both methods,
+ * typically based on a unique identifier (e.g. a UId).
+ * <p>
  * @param variableDescriptor The variable this {@link VariableId} refers to.
  * @param entity The entity this {@link VariableId} refers to.
  */
@@ -14,8 +18,8 @@ public record VariableId<Solution_>(VariableDescriptor<Solution_> variableDescri
     @Override
     public boolean equals(Object other) {
         if (other instanceof VariableId<?> variableId) {
-            return variableDescriptor == variableId.variableDescriptor &&
-                    entity == variableId.entity;
+            return variableDescriptor.equals(variableId.variableDescriptor) &&
+                    entity.equals(variableId.entity);
         }
         return false;
     }