(kafka) branch 3.9 updated: KAFKA-20117 Improve ClusterControlManager error message (#21731)

[chia7712]

This is an automated email from the ASF dual-hosted git repository.

chia7712 pushed a commit to branch 3.9
in repository https://gitbox.apache.org/repos/asf/kafka.git


The following commit(s) were added to refs/heads/3.9 by this push:
     new 1c19815557d KAFKA-20117 Improve ClusterControlManager error message 
(#21731)
1c19815557d is described below

commit 1c19815557df42efd265fb66d44332ac7d3729b4
Author: Nick Guo <lansg0...@gmail.com>
AuthorDate: Thu Mar 19 05:56:28 2026 +0800

    KAFKA-20117 Improve ClusterControlManager error message (#21731)
    
    jira: https://issues.apache.org/jira/browse/KAFKA-20117
    
    Improve the broker registration error message for `metadata.version`
    mismatches.
    
    Reviewers: Chia-Ping Tsai <chia7...@gmail.com>
---
 .../apache/kafka/controller/ClusterControlManager.java | 18 +++++++++++++++---
 .../kafka/controller/ClusterControlManagerTest.java    |  8 ++++----
 2 files changed, 19 insertions(+), 7 deletions(-)

diff --git 
a/metadata/src/main/java/org/apache/kafka/controller/ClusterControlManager.java 
b/metadata/src/main/java/org/apache/kafka/controller/ClusterControlManager.java
index b0b43f05a4c..55f122bce95 100644
--- 
a/metadata/src/main/java/org/apache/kafka/controller/ClusterControlManager.java
+++ 
b/metadata/src/main/java/org/apache/kafka/controller/ClusterControlManager.java
@@ -525,10 +525,22 @@ public class ClusterControlManager {
         int defaultVersion = 
feature.name().equals(MetadataVersion.FEATURE_NAME) ? 1 : 0; // The default 
value for MetadataVersion is 1 not 0.
         short finalized = finalizedFeatures.versionOrDefault(feature.name(), 
(short) defaultVersion);
         if (!VersionRange.of(feature.minSupportedVersion(), 
feature.maxSupportedVersion()).contains(finalized)) {
+            boolean isMetadataVersion = 
feature.name().equals(MetadataVersion.FEATURE_NAME);
+            String finalizedDisplay = isMetadataVersion
+                ? finalized + " (" + 
MetadataVersion.fromFeatureLevel(finalized) + ")"
+                : String.valueOf(finalized);
+            String minSupportedDisplay = isMetadataVersion
+                ? feature.minSupportedVersion() + " (" +
+                    
MetadataVersion.fromFeatureLevel(feature.minSupportedVersion()) + ")"
+                : String.valueOf(feature.minSupportedVersion());
+            String maxSupportedDisplay = isMetadataVersion
+                ? feature.maxSupportedVersion() + " (" +
+                    
MetadataVersion.fromFeatureLevel(feature.maxSupportedVersion()) + ")"
+                : String.valueOf(feature.maxSupportedVersion());
             throw new UnsupportedVersionException("Unable to register because 
the broker " +
-                "does not support finalized version " + finalized + " of " + 
feature.name() +
-                    ". The broker wants a version between " + 
feature.minSupportedVersion() + " and " +
-                    feature.maxSupportedVersion() + ", inclusive.");
+                "does not support finalized version " + finalizedDisplay + " 
of " + feature.name() +
+                    ". The broker wants a version between " + 
minSupportedDisplay + " and " +
+                    maxSupportedDisplay + ", inclusive.");
         }
         // A feature is not found in the finalizedFeature map if it is unknown 
to the controller or set to 0 (feature not enabled).
         if (!finalizedFeatures.featureNames().contains(feature.name()))
diff --git 
a/metadata/src/test/java/org/apache/kafka/controller/ClusterControlManagerTest.java
 
b/metadata/src/test/java/org/apache/kafka/controller/ClusterControlManagerTest.java
index 786891e695b..f8f8c80cc16 100644
--- 
a/metadata/src/test/java/org/apache/kafka/controller/ClusterControlManagerTest.java
+++ 
b/metadata/src/test/java/org/apache/kafka/controller/ClusterControlManagerTest.java
@@ -686,8 +686,8 @@ public class ClusterControlManagerTest {
                 build();
         clusterControl.activate();
 
-        assertEquals("Unable to register because the broker does not support 
finalized version 4 of " +
-            "metadata.version. The broker wants a version between 1 and 1, 
inclusive.",
+        assertEquals("Unable to register because the broker does not support 
finalized version 4 (3.3-IV0) of " +
+            "metadata.version. The broker wants a version between 1 (3.0-IV1) 
and 1 (3.0-IV1), inclusive.",
             assertThrows(UnsupportedVersionException.class,
                 () -> clusterControl.registerBroker(
                     new BrokerRegistrationRequestData().
@@ -698,8 +698,8 @@ public class ClusterControlManagerTest {
                     123L,
                     
featureControl.finalizedFeatures(Long.MAX_VALUE))).getMessage());
 
-        assertEquals("Unable to register because the broker does not support 
finalized version 4 of " +
-            "metadata.version. The broker wants a version between 7 and 7, 
inclusive.",
+        assertEquals("Unable to register because the broker does not support 
finalized version 4 (3.3-IV0) of " +
+            "metadata.version. The broker wants a version between 7 (3.3-IV3) 
and 7 (3.3-IV3), inclusive.",
             assertThrows(UnsupportedVersionException.class,
                 () -> clusterControl.registerBroker(
                     new BrokerRegistrationRequestData().