diff --git a/modules/join/src/java/org/apache/lucene/search/join/ToParentBlockJoinCollector.java b/modules/join/src/java/org/apache/lucene/search/join/ToParentBlockJoinCollector.java
index 63d4af322b7..aebd5e998e7 100644
--- a/modules/join/src/java/org/apache/lucene/search/join/ToParentBlockJoinCollector.java
+++ b/modules/join/src/java/org/apache/lucene/search/join/ToParentBlockJoinCollector.java
@@ -18,7 +18,7 @@ package org.apache.lucene.search.join;
  */
 
 import org.apache.lucene.index.AtomicReaderContext;
-import org.apache.lucene.index.IndexWriter;
+import org.apache.lucene.index.IndexWriter; // javadocs
 import org.apache.lucene.search.*;
 import org.apache.lucene.search.Scorer.ChildScorer;
 import org.apache.lucene.search.grouping.GroupDocs;
@@ -100,7 +100,9 @@ public class ToParentBlockJoinCollector extends Collector {
   private float maxScore = Float.NaN;
 
   /*  Creates a ToParentBlockJoinCollector.  The provided sort must
-   *  not be null. */
+   *  not be null.  If you pass true trackScores, all
+   *  ToParentBlockQuery instances must not use
+   *  ScoreMode.None. */
   public ToParentBlockJoinCollector(Sort sort, int numParentHits, boolean trackScores, boolean trackMaxScore) throws IOException {
     // TODO: allow null sort to be specialized to relevance
     // only collector
diff --git a/modules/join/src/java/org/apache/lucene/search/join/ToParentBlockJoinQuery.java b/modules/join/src/java/org/apache/lucene/search/join/ToParentBlockJoinQuery.java
index 96cb1090b94..914b54850e9 100644
--- a/modules/join/src/java/org/apache/lucene/search/join/ToParentBlockJoinQuery.java
+++ b/modules/join/src/java/org/apache/lucene/search/join/ToParentBlockJoinQuery.java
@@ -267,7 +267,7 @@ public class ToParentBlockJoinQuery extends Query {
 
     float[] swapChildScores(float[] other) {
       if (scoreMode == ScoreMode.None) {
-        throw new IllegalStateException("ScoreMode is None");
+        throw new IllegalStateException("ScoreMode is None; you must pass trackScores=false to ToParentBlockJoinCollector");
       }
       final float[] ret = pendingChildScores;
       if (other == null) {