branch-4.0: [opt](catalog) Improve error messages in connectivity tests by using root cause information #58184 (#58358)

Cherry-picked from #58184

Co-authored-by: zy-kkk <[email protected]>

Author: github-actions[bot]

fe/fe-core/src/main/java/org/apache/doris/datasource/connectivity/AbstractS3CompatibleConnectivityTester.java

@@ -66,4 +66,10 @@ public void testFeConnection() throws Exception {
             client.headBucket(b -> b.bucket(s3Uri.getBucket()));
         }
     }
+
+    @Override
+    public String getErrorHint() {
+        return "Please check S3 credentials (access_key and secret_key or IAM role), "
+                + "region, and bucket (warehouse location) access permissions";
+    }
 }

fe/fe-core/src/main/java/org/apache/doris/datasource/connectivity/CatalogConnectivityTestCoordinator.java

@@ -18,6 +18,7 @@
 package org.apache.doris.datasource.connectivity;
 
 import org.apache.doris.common.DdlException;
+import org.apache.doris.common.util.Util;
 import org.apache.doris.datasource.property.metastore.HiveGlueMetaStoreProperties;
 import org.apache.doris.datasource.property.metastore.HiveHMSProperties;
 import org.apache.doris.datasource.property.metastore.IcebergGlueMetaStoreProperties;
@@ -94,8 +95,10 @@ private void testMetadataService() throws DdlException {
         try {
             metaTester.testConnection();
         } catch (Exception e) {
-            throw new DdlException(metaTester.getTestType() + " connectivity test failed: "
-                    + e.getMessage());
+            String hint = metaTester.getErrorHint();
+            String errorMsg = metaTester.getTestType() + " connectivity test failed: " + hint
+                    + " Root cause: " + Util.getRootCauseMessage(e);
+            throw new DdlException(errorMsg);
         }
 
         // Store warehouse location for later use
@@ -142,15 +145,20 @@ private void testObjectStorageForWarehouse(StorageProperties testObjectStoragePr
         try {
             tester.testFeConnection();
         } catch (Exception e) {
-            throw new DdlException(tester.getTestType() + " connectivity test failed: " + e.getMessage());
+            String hint = tester.getErrorHint();
+            String errorMsg = tester.getTestType() + " connectivity test failed: " + hint
+                    + " Root cause: " + Util.getRootCauseMessage(e);
+            throw new DdlException(errorMsg);
         }
 
         // Test BE connection
         try {
             tester.testBeConnection();
         } catch (Exception e) {
-            throw new DdlException(tester.getTestType()
-                    + " connectivity test failed (compute node): " + e.getMessage());
+            String hint = tester.getErrorHint();
+            String errorMsg = tester.getTestType() + " connectivity test failed (compute node): " + hint
+                    + " Root cause: " + Util.getRootCauseMessage(e);
+            throw new DdlException(errorMsg);
         }
     }
 
@@ -240,14 +248,20 @@ private void testExplicitlyConfiguredHdfs() throws DdlException {
         try {
             tester.testFeConnection();
         } catch (Exception e) {
-            throw new DdlException("HDFS connectivity test failed: " + e.getMessage());
+            String hint = tester.getErrorHint();
+            String errorMsg = "HDFS connectivity test failed: " + hint
+                    + " Root cause: " + Util.getRootCauseMessage(e);
+            throw new DdlException(errorMsg);
         }
 
         // Test BE connection
         try {
             tester.testBeConnection();
         } catch (Exception e) {
-            throw new DdlException("HDFS connectivity test failed (compute node): " + e.getMessage());
+            String hint = tester.getErrorHint();
+            String errorMsg = "HDFS connectivity test failed (compute node): " + hint
+                    + " Root cause: " + Util.getRootCauseMessage(e);
+            throw new DdlException(errorMsg);
         }
     }
 

fe/fe-core/src/main/java/org/apache/doris/datasource/connectivity/HdfsCompatibleConnectivityTester.java

@@ -37,6 +37,12 @@ public String getTestType() {
         return "HDFS";
     }
 
+    @Override
+    public String getErrorHint() {
+        return "Please check HDFS namenode connectivity (fs.defaultFS), user permissions, and "
+                + "Kerberos configuration if applicable";
+    }
+
     @Override
     public void testFeConnection() throws Exception {
         // TODO: Implement HDFS connectivity test in the future if needed

fe/fe-core/src/main/java/org/apache/doris/datasource/connectivity/HiveGlueMetaStoreConnectivityTester.java

@@ -34,6 +34,12 @@ public String getTestType() {
         return "Hive Glue";
     }
 
+    @Override
+    public String getErrorHint() {
+        return "Please check AWS Glue credentials (access_key and secret_key or IAM role), region, "
+                + "and endpoint";
+    }
+
     @Override
     public void testConnection() throws Exception {
         glueTester.testConnection();

fe/fe-core/src/main/java/org/apache/doris/datasource/connectivity/HiveHMSConnectivityTester.java

@@ -33,6 +33,11 @@ public String getTestType() {
         return "Hive HMS";
     }
 
+    @Override
+    public String getErrorHint() {
+        return "Please check Hive Metastore Server connectivity (hive metastore uris)";
+    }
+
     @Override
     public void testConnection() throws Exception {
         hmsTester.testConnection();

fe/fe-core/src/main/java/org/apache/doris/datasource/connectivity/IcebergGlueMetaStoreConnectivityTester.java

@@ -20,7 +20,12 @@
 import org.apache.doris.datasource.property.metastore.AWSGlueMetaStoreBaseProperties;
 import org.apache.doris.datasource.property.metastore.AbstractIcebergProperties;
 
+import org.apache.commons.lang3.StringUtils;
+
+import java.util.regex.Pattern;
+
 public class IcebergGlueMetaStoreConnectivityTester extends AbstractIcebergConnectivityTester {
+    private static final Pattern S3_LOCATION_PATTERN = Pattern.compile("^(s3|s3a)://.+");
     private final AWSGlueMetaStoreBaseConnectivityTester glueTester;
 
     public IcebergGlueMetaStoreConnectivityTester(AbstractIcebergProperties properties,
@@ -34,8 +39,36 @@ public String getTestType() {
         return "Iceberg Glue";
     }
 
+    @Override
+    public String getErrorHint() {
+        return "Please check AWS Glue credentials (access_key and secret_key or IAM role), "
+                + "region, warehouse location, and endpoint";
+    }
+
     @Override
     public void testConnection() throws Exception {
         glueTester.testConnection();
     }
+
+    @Override
+    public String getTestLocation() {
+        String warehouse = properties.getWarehouse();
+        if (StringUtils.isBlank(warehouse)) {
+            return null;
+        }
+
+        String location = validateS3Location(warehouse);
+        if (location == null) {
+            throw new IllegalArgumentException(
+                    "Iceberg Glue warehouse location must be in S3 format (s3:// or s3a://), but got: " + warehouse);
+        }
+        return location;
+    }
+
+    private String validateS3Location(String location) {
+        if (StringUtils.isNotBlank(location) && S3_LOCATION_PATTERN.matcher(location).matches()) {
+            return location;
+        }
+        return null;
+    }
 }

fe/fe-core/src/main/java/org/apache/doris/datasource/connectivity/IcebergHMSConnectivityTester.java

@@ -33,6 +33,11 @@ public String getTestType() {
         return "Iceberg HMS";
     }
 
+    @Override
+    public String getErrorHint() {
+        return "Please check Hive Metastore Server connectivity (hive metastore uris)";
+    }
+
     @Override
     public void testConnection() throws Exception {
         hmsTester.testConnection();

fe/fe-core/src/main/java/org/apache/doris/datasource/connectivity/IcebergRestConnectivityTester.java

@@ -43,6 +43,12 @@ public String getTestType() {
         return "Iceberg REST";
     }
 
+    @Override
+    public String getErrorHint() {
+        return "Please check Iceberg REST Catalog URI, authentication credentials (OAuth2 or SigV4), "
+                + "warehouse location, and endpoint connectivity";
+    }
+
     @Override
     public void testConnection() throws Exception {
         Map<String, String> restProps = ((IcebergRestProperties) properties).getIcebergRestCatalogProperties();

fe/fe-core/src/main/java/org/apache/doris/datasource/connectivity/IcebergS3TablesMetaStoreConnectivityTester.java

@@ -25,6 +25,12 @@ protected IcebergS3TablesMetaStoreConnectivityTester(
         super(properties);
     }
 
+    @Override
+    public String getErrorHint() {
+        return "Please check S3 credentials (access_key and secret_key or IAM role), endpoint, region, "
+                + "and warehouse location";
+    }
+
     @Override
     public void testConnection() throws Exception {
         // TODO: Implement Iceberg S3 Tables connectivity test in the future if needed

fe/fe-core/src/main/java/org/apache/doris/datasource/connectivity/MetaConnectivityTester.java

@@ -34,4 +34,12 @@ default String getTestLocation() {
     default String getTestType() {
         return "Meta";
     }
+
+    /**
+     * Returns error hint for this connectivity test.
+     * Subclasses can override to provide specific hints for troubleshooting.
+     */
+    default String getErrorHint() {
+        return "";
+    }
 }