apache/iceberg · error · IllegalArgumentException

Unknown type <category>

Error message

Unknown type <category>

What it means

HiveSchemaConverter.convertType throws IllegalArgumentException for Hive type categories it does not handle — UNION explicitly falls into UNION/default with this error. Iceberg has no union type, so conversion cannot proceed.

Source

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

            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++;
        return Types.MapType.ofOptional(keyId, valueId, keyType, valueType);
      case LIST:
        ListTypeInfo listTypeInfo = (ListTypeInfo) typeInfo;
        Type listType = convertType(listTypeInfo.getListElementTypeInfo());
        return Types.ListType.ofOptional(id++, listType);
      case UNION:
      default:
        throw new IllegalArgumentException("Unknown type " + typeInfo.getCategory());
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Flatten the uniontype column into separate concrete columns (one per variant) before conversion.
2. Convert the union member types manually and store as a struct, string, or binary if a lossless mapping is not needed.
3. Extend HiveSchemaConverter with a UNION case mapping to a chosen Iceberg type if your workload needs it.

Example fix

// before
-- col: uniontype<int,string>
// after
ALTER TABLE events CHANGE COLUMN col col struct<a:int,b:string>; // or explode to typed columns

if (hiveSchema.contains(unionTypeInfo)) { throw new IllegalArgumentException("Flatten uniontype columns before conversion"); }

boolean isUnion(TypeInfo ti) { return ti.getCategory() == ObjectInspector.Category.UNION; }

try { schema = HiveSchemaConverter.convert(typeInfo); } catch (IllegalArgumentException e) { /* flatten union columns and retry */ }

When it happens

Trigger: Calling HiveSchemaConverter.convert on a TypeInfo tree containing a UNION type (Hive uniontype columns) or any unrecognized category.

Common situations: Migrating Hive tables that use uniontype columns; schemas produced by ETL frameworks that emit Hive unions; corrupted/unknown category values from unusual metastore versions.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Unsupported Hive type (<category>) for Iceberg tables.
• <type> is not supported
• Unsupported primitive type:
• Unsupported type ID:
• Avro does not support TIME type with precision: <precision>,

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