apache/iceberg · error · UnsupportedOperationException

Cannot handle

Error message

Cannot handle

What it means

OrcSchemaWithTypeVisitor.visit maps an ORC TypeDescription tree (with its Iceberg Types counterpart) to visitor callbacks. ORC UNION types cannot be represented in Iceberg, so the visitor throws UnsupportedOperationException when it encounters one. Like the typeless OrcSchemaVisitor, this rejects the schema before any mapping is produced.

Source

Thrown at orc/src/main/java/org/apache/iceberg/orc/OrcSchemaWithTypeVisitor.java:48

      org.apache.iceberg.Schema iSchema,
      TypeDescription schema,
      OrcSchemaWithTypeVisitor<T> visitor) {
    return visit(iSchema.asStruct(), schema, visitor);
  }

  public static <T> T visit(
      Type iType, TypeDescription schema, OrcSchemaWithTypeVisitor<T> visitor) {
    switch (schema.getCategory()) {
      case STRUCT:
        String structType = schema.getAttributeValue(ORCSchemaUtil.ICEBERG_STRUCT_TYPE_ATTRIBUTE);
        if (ORCSchemaUtil.VARIANT.equalsIgnoreCase(structType)) {
          return visitVariant(iType != null ? iType.asVariantType() : null, schema, visitor);
        } else {
          return visitRecord(iType != null ? iType.asStructType() : null, schema, visitor);
        }

      case UNION:
        throw new UnsupportedOperationException("Cannot handle " + schema);

      case LIST:
        Types.ListType list = iType != null ? iType.asListType() : null;
        return visitor.list(
            list,
            schema,
            visit(list != null ? list.elementType() : null, schema.getChildren().get(0), visitor));

      case MAP:
        Types.MapType map = iType != null ? iType.asMapType() : null;
        return visitor.map(
            map,
            schema,
            visit(map != null ? map.keyType() : null, schema.getChildren().get(0), visitor),
            visit(map != null ? map.valueType() : null, schema.getChildren().get(1), visitor));

      default:
        return visitor.primitive(iType != null ? iType.asPrimitiveType() : null, schema);

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Eliminate UNION types from the ORC schema (flatten to a struct with a discriminator/tag column) and rewrite the data.
  2. Skip or prune union columns before conversion if the tooling allows selecting only needed columns.
  3. Convert the file format to Parquet/Avro where the data model supports the equivalent of the union.

Example fix

// before: uniontype<int,string>
// after: struct<tag: int, int_val: int, str_val: string>
Defensive patterns

Strategy: validation

Validate before calling

for (TypeDescription child : schema.getChildren()) { if (child.getCategory() == TypeDescription.Category.UNION) { throw new IllegalArgumentException("ORC union column not supported: " + child); } }

Try / catch

try { converted = OrcSchemaWithTypeVisitor.visit(icebergType, orcSchema, visitor); } catch (UnsupportedOperationException e) { if (e.getMessage().startsWith("Cannot handle")) { logAndReject(orcSchema); } else throw e; }

Prevention

When it happens

Trigger: Calling OrcSchemaWithTypeVisitor.visit (used by ORC-to-Iceberg schema conversion in ORCSchemaUtil and readers) on an ORC schema containing a UNION node.

Common situations: Converting an externally written ORC file schema to an Iceberg schema; reading ORC data files produced by Trino/Hive that contain union columns.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

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