apache/iceberg · error · IllegalArgumentException

Unsupported Hive type (<category>) for Iceberg tables.

Error message

Unsupported Hive type (<category>) for Iceberg tables.

What it means

HiveSchemaConverter.convertType throws IllegalArgumentException when it meets a Hive primitive type category that has no Iceberg type mapping (anything not handled by the switch and not TIMESTAMPLOCALTZ). Iceberg cannot represent that primitive type in its schema, so schema conversion from Hive fails immediately.

Source

Thrown at hive-metastore/src/main/java/org/apache/iceberg/hive/HiveSchemaConverter.java:129

            return Types.StringType.get();
          case STRING:
            return Types.StringType.get();
          case TIMESTAMP:
            return Types.TimestampType.withoutZone();
          case DATE:
            return Types.DateType.get();
          case DECIMAL:
            DecimalTypeInfo decimalTypeInfo = (DecimalTypeInfo) typeInfo;
            return Types.DecimalType.of(decimalTypeInfo.precision(), decimalTypeInfo.scale());
          case INTERVAL_YEAR_MONTH:
          case INTERVAL_DAY_TIME:
          default:
            // special case for Timestamp with Local TZ which is only available in Hive3
            if ("TIMESTAMPLOCALTZ"
                .equalsIgnoreCase(((PrimitiveTypeInfo) typeInfo).getPrimitiveCategory().name())) {
              return Types.TimestampType.withZone();
            }
            throw new IllegalArgumentException(
                "Unsupported Hive type ("
                    + ((PrimitiveTypeInfo) typeInfo).getPrimitiveCategory()
                    + ") for Iceberg tables.");
        }
      case STRUCT:
        StructTypeInfo structTypeInfo = (StructTypeInfo) typeInfo;
        List<Types.NestedField> fields =
            convertInternal(
                structTypeInfo.getAllStructFieldNames(),
                structTypeInfo.getAllStructFieldTypeInfos(),
                Collections.emptyList());
        return Types.StructType.of(fields);
      case MAP:
        MapTypeInfo mapTypeInfo = (MapTypeInfo) typeInfo;
        Type keyType = convertType(mapTypeInfo.getMapKeyTypeInfo());
        Type valueType = convertType(mapTypeInfo.getMapValueTypeInfo());
        int keyId = id++;
        int valueId = id++;

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Alter the Hive column to a supported type (string, int, bigint, double, boolean, date, timestamp, decimal, binary-compatible) before converting.
  2. Add an explicit case in HiveSchemaConverter for the category if it has a sensible Iceberg mapping.
  3. Exclude/transform the offending column during migration and recreate it as a supported Iceberg type.

Example fix

// before
-- column 'tz' is timestamp with local time zone on an older metastore
// after
ALTER TABLE events CHANGE COLUMN tz tz timestamp; -- or upgrade to Hive3 so TIMESTAMPLOCALTZ maps to timestamptz
Defensive patterns

Strategy: validation

Validate before calling

for (TypeInfo ti : hiveSchema.getAllStructFieldTypeInfo()) { if (((PrimitiveTypeInfo) ti).getPrimitiveCategory() == PrimitiveCategory.UNKNOWN) throw new IllegalStateException("unsupported primitive"); }

Try / catch

try { schema = HiveSchemaConverter.convert(hiveSchema); } catch (IllegalArgumentException e) { /* pre-map offending columns */ }

Prevention

When it happens

Trigger: Converting a Hive table schema containing an unmapped primitive (e.g. DECIMAL outside supported bounds is mapped elsewhere; typically exotic or hive3-only categories) via HiveSchemaConverter.convert on a StructTypeInfo field.

Common situations: Migrating legacy Hive tables to Iceberg with types like BINARY variants or vendor-specific categories; Hive2/Hive3 metastore differences (e.g. TIMESTAMP WITH LOCAL TIME ZONE handled only as the TIMESTAMPLOCALTZ special case); schemas created by other tools with unsupported primitives.

Related errors

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/b034ca39c2717eb8. Report an issue: GitHub.