[SPARK-21529][4.X][SQL] Improve the error message for unsupported Hive union type

### What changes were proposed in this pull request?

Backport of #56775 to `branch-4.x` because the original change conflicts on this branch.

Detect unsupported Hive `uniontype<...>` values when converting Hive `FieldSchema` types to Spark SQL types and raise a dedicated `UNSUPPORTED_HIVE_TYPE` error instead of the generic `CANNOT_RECOGNIZE_HIVE_TYPE` parser error.

This is a cherry-pick of the merged master commit c90cad6. The only conflict was in `error-conditions.json`: `branch-4.x` does not have the `UNSUPPORTED_HIVE_FUNCTION_TYPE` / `UNSUPPORTED_HIVE_METASTORE_VERSION_FOR_JAVA` entries that exist on master, so the new `UNSUPPORTED_HIVE_TYPE` entry is placed directly between `UNSUPPORTED_GROUPING_EXPRESSION` and `UNSUPPORTED_INSERT`. The Scala changes apply unchanged.

### Why are the changes needed?

Spark SQL does not support Hive union types. Today the failure message comes from the parser path and does not clearly identify that the Hive union type is unsupported.

### Does this PR introduce _any_ user-facing change?

Yes. Reading a Hive table column that uses `uniontype<...>` now reports `UNSUPPORTED_HIVE_TYPE` with the offending Hive type and column name.

### How was this patch tested?

Cherry-picked from the merged master commit c90cad6, which passed CI and review as #56775. The production Scala hunks apply unchanged on `branch-4.x`; only the `error-conditions.json` entry placement differed and was re-validated (valid JSON, alphabetical ordering, one structural token per line). CI here runs `HiveClientImplSuite` and the `SparkThrowableSuite` "Error conditions are correctly formatted" golden check.

### Was this patch authored or co-authored using generative AI tooling?

Yes. GitHub Copilot assisted with preparing and validating this change.

Closes #56929 from AgenticSpark/agenticspark/SPARK-21529-branch-4.x.

Authored-by: AgenticSpark <jianglie2023@gmail.com>
Signed-off-by: Max Gekk <max.gekk@gmail.com>

Author: AgenticSpark

common/utils/src/main/resources/error/error-conditions.json

@@ -8641,6 +8641,12 @@
     ],
     "sqlState" : "42K0E"
   },
+  "UNSUPPORTED_HIVE_TYPE" : {
+    "message" : [
+      "Cannot read the Hive type <fieldType> of the column <fieldName> because Spark SQL does not support this data type."
+    ],
+    "sqlState" : "0A000"
+  },
   "UNSUPPORTED_INSERT" : {
     "message" : [
       "Can't insert into the target."

sql/catalyst/src/main/scala/org/apache/spark/sql/errors/QueryExecutionErrors.scala

@@ -1696,6 +1696,13 @@ private[sql] object QueryExecutionErrors extends QueryErrorsBase with ExecutionE
       cause = e)
   }
 
+  def unsupportedHiveTypeError(fieldType: String, fieldName: String): Throwable = {
+    new SparkUnsupportedOperationException(
+      errorClass = "UNSUPPORTED_HIVE_TYPE",
+      messageParameters = Map(
+        "fieldType" -> toSQLType(fieldType),
+        "fieldName" -> toSQLId(fieldName)))
+  }
   def getTablesByTypeUnsupportedByHiveVersionError(): SparkUnsupportedOperationException = {
     new SparkUnsupportedOperationException(
       errorClass = "GET_TABLES_BY_TYPE_UNSUPPORTED_BY_HIVE_VERSION")

sql/hive/src/main/scala/org/apache/spark/sql/hive/client/HiveClientImpl.scala

@@ -1139,6 +1139,11 @@ private[hive] object HiveClientImpl extends Logging {
       CatalystSqlParser.parseDataType(typeStr)
     } catch {
       case e: ParseException =>
+        // Hive's union type (uniontype<...>) is not supported by Spark SQL and makes the parser
+        // fail with a generic message. Detect it and report a clearer error (SPARK-21529).
+        if (hc.getType.toLowerCase(Locale.ROOT).contains("uniontype<")) {
+          throw QueryExecutionErrors.unsupportedHiveTypeError(hc.getType, hc.getName)
+        }
         throw QueryExecutionErrors.cannotRecognizeHiveTypeError(e, typeStr, hc.getName)
     }
   }

sql/hive/src/test/scala/org/apache/spark/sql/hive/client/HiveClientImplSuite.scala

@@ -0,0 +1,49 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.spark.sql.hive.client
+
+import org.apache.hadoop.hive.metastore.api.FieldSchema
+
+import org.apache.spark.{SparkFunSuite, SparkUnsupportedOperationException}
+
+class HiveClientImplSuite extends SparkFunSuite {
+
+  test("SPARK-21529: a clear error is raised for an unsupported Hive union type") {
+    val column = new FieldSchema("c", "uniontype<int,string>", null)
+    checkError(
+      exception = intercept[SparkUnsupportedOperationException] {
+        HiveClientImpl.fromHiveColumn(column)
+      },
+      condition = "UNSUPPORTED_HIVE_TYPE",
+      parameters = Map(
+        "fieldType" -> "\"UNIONTYPE<INT,STRING>\"",
+        "fieldName" -> "`c`"))
+  }
+
+  test("SPARK-21529: a Hive union type nested in a struct is detected") {
+    val column = new FieldSchema("c", "struct<a:uniontype<int,string>>", null)
+    checkError(
+      exception = intercept[SparkUnsupportedOperationException] {
+        HiveClientImpl.fromHiveColumn(column)
+      },
+      condition = "UNSUPPORTED_HIVE_TYPE",
+      parameters = Map(
+        "fieldType" -> "\"STRUCT<A:UNIONTYPE<INT,STRING>>\"",
+        "fieldName" -> "`c`"))
+  }
+}