diff --git a/docs/pages/release_notes.md b/docs/pages/release_notes.md
index e8339a5c95..35baaadd48 100644
--- a/docs/pages/release_notes.md
+++ b/docs/pages/release_notes.md
@@ -28,7 +28,7 @@ when used on the CLI or in a ruleset XML file:
 - `<lang-name>-<ruleset-name>`, eg `java-basic`, which resolves to `rulesets/java/basic.xml`
 - the internal release number, eg `600`, which resolves to `rulesets/releases/600.xml`
 
-Use the explicit forms of these references
+Use the explicit forms of these references to be compatible with PMD 7.
 
 #### Deprecated API
 
diff --git a/pmd-core/src/main/java/net/sourceforge/pmd/RuleSetReferenceId.java b/pmd-core/src/main/java/net/sourceforge/pmd/RuleSetReferenceId.java
index 79ef421fe1..82028f9993 100644
--- a/pmd-core/src/main/java/net/sourceforge/pmd/RuleSetReferenceId.java
+++ b/pmd-core/src/main/java/net/sourceforge/pmd/RuleSetReferenceId.java
@@ -77,6 +77,9 @@ import net.sourceforge.pmd.util.ResourceLoader;
 @InternalApi
 public class RuleSetReferenceId {
 
+    // todo this class has issues... What is even an "external" ruleset?
+    //  terminology and API should be clarified.
+
     // use the logger of RuleSetFactory, because the warnings conceptually come from there.
     private static final Logger LOG = Logger.getLogger(RuleSetFactory.class.getName());
 
diff --git a/pmd-java/src/test/java/net/sourceforge/pmd/cli/CLITest.java b/pmd-java/src/test/java/net/sourceforge/pmd/cli/CLITest.java
index 22bcfca35e..defff23883 100644
--- a/pmd-java/src/test/java/net/sourceforge/pmd/cli/CLITest.java
+++ b/pmd-java/src/test/java/net/sourceforge/pmd/cli/CLITest.java
@@ -80,8 +80,8 @@ public class CLITest extends BaseCLITest {
     public void testWrongRuleset() {
         String[] args = { "-d", SOURCE_FOLDER, "-f", "text", "-R", "category/java/designn.xml", };
         String log = runTest(StatusCode.ERROR, args);
-        assertThat(log, containsString("Can't find resource 'category/java/designn.xml' for rule 'null'."
-                                           + "  Make sure the resource is a valid file"));
+        assertThat(log, containsString("Cannot resolve rule/ruleset reference "
+                                       + "'category/java/designn.xml'"));
     }
 
     /**
@@ -91,8 +91,8 @@ public class CLITest extends BaseCLITest {
     public void testWrongRulesetWithRulename() {
         String[] args = { "-d", SOURCE_FOLDER, "-f", "text", "-R", "category/java/designn.xml/UseCollectionIsEmpty", };
         String log = runTest(StatusCode.ERROR, args);
-        assertThat(log, containsString("Can't find resource 'category/java/designn.xml' for rule "
-                                           + "'UseCollectionIsEmpty'."));
+        assertThat(log, containsString("Cannot resolve rule/ruleset reference"
+                                       + " 'category/java/designn.xml/UseCollectionIsEmpty'"));
     }
 
     /**