What causes "Cannot handle " in apache/iceberg?

Remove UNION columns from the ORC schema, or re-express them as structs with a tag field before the file is referenced by Iceberg.

apache/iceberg · error · UnsupportedOperationException

Cannot handle

Error message

Cannot handle

What it means

OrcSchemaVisitor.visit walks an ORC TypeDescription tree and dispatches to visitor callbacks per node type. ORC UNION types have no Iceberg counterpart, so the visitor explicitly rejects them with UnsupportedOperationException. This happens before any visitor callback runs.

Source

Thrown at orc/src/main/java/org/apache/iceberg/orc/OrcSchemaVisitor.java:52

    List<TypeDescription> fields = schema.getChildren();
    List<String> names = schema.getFieldNames();

    return visitFields(fields, names, visitor);
  }

  public static <T> T visit(TypeDescription schema, OrcSchemaVisitor<T> visitor) {
    switch (schema.getCategory()) {
      case STRUCT:
        String structType = schema.getAttributeValue(ORCSchemaUtil.ICEBERG_STRUCT_TYPE_ATTRIBUTE);
        if (ORCSchemaUtil.VARIANT.equalsIgnoreCase(structType)) {
          return visitVariant(schema, visitor);
        } else {
          return visitRecord(schema, visitor);
        }

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

      case LIST:
        final T elementResult;

        TypeDescription element = schema.getChildren().get(0);
        visitor.beforeElementField(element);
        try {
          elementResult = visit(element, visitor);
        } finally {
          visitor.afterElementField(element);
        }
        return visitor.list(schema, elementResult);

      case MAP:
        final T keyResult;
        final T valueResult;

        TypeDescription key = schema.getChildren().get(0);

View on GitHub (pinned to 86d9c8fc54)

Solutions

Remove UNION columns from the ORC schema, or re-express them as structs with a tag field before the file is referenced by Iceberg.
Rewrite the ORC data with a union-free schema (e.g. via a Spark/Hive CTAS that flattens the union).
If the union is in an unrelated column, project it out in your read path so the visitor never sees that subtree, if the API used allows schema pruning before visiting.

Example fix

// before: ORC schema with union<int,string>
// after: struct with tag
case int(1) tag, oneof: struct<a: int, b: string>

Defensive patterns

Strategy: validation

Validate before calling

boolean hasUnion = false; // pre-scan schema
org.apache.orc.TypeDescription root = schema;
if (root.getCategory() == TypeDescription.Category.UNION) hasUnion = true;
// or check each declared column's category before visiting

Try / catch

try { OrcSchemaVisitor.visit(schema, visitor); } catch (UnsupportedOperationException e) { if (e.getMessage().startsWith("Cannot handle")) { rejectFile(schemaPath); } else throw e; }

Prevention

Reject ORC files with union columns at ingestion time
Prefer struct-with-tag designs over ORC unions when writing with external engines
Validate schemas with ORC tooling before registering files with Iceberg

When it happens

Trigger: Calling OrcSchemaVisitor.visit (directly, or via OrcMetrics.statsColumns, ID mappings, or ORC file read/write paths) on a schema, or reading an ORC file whose schema contains a UNION type.

Common situations: See trigger scenarios.

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/ece98ec122e0da39. Report an issue: GitHub.