apache/iceberg · error · IllegalArgumentException

Unhandled type

Error message

Unhandled type

What it means

GenericOrcReader.primitive() throws IllegalArgumentException with "Unhandled type " when the ORC file's primitive column category is not one of the categories the reader supports (e.g., an exotic ORC type or union). It is a defensive fallback for ORC types with no Iceberg reader mapping.

Source

Thrown at orc/src/main/java/org/apache/iceberg/data/orc/GenericOrcReader.java:165

        case VARCHAR:
        case STRING:
          return GenericOrcReaders.strings();
        case BINARY:
          switch (iPrimitive.typeId()) {
            case UUID:
              return GenericOrcReaders.uuids();
            case FIXED:
              return OrcValueReaders.bytes();
            case BINARY:
              return GenericOrcReaders.bytes();
            default:
              throw new IllegalStateException(
                  String.format(
                      "Invalid iceberg type %s corresponding to ORC type %s",
                      iPrimitive, primitive));
          }
        default:
          throw new IllegalArgumentException("Unhandled type " + primitive);
      }
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Rewrite the ORC files with supported column types (remove/flatten exotic types).
  2. Convert the files to a format/type combination Iceberg supports (e.g., rewrite via Spark).
  3. Upgrade Iceberg to check for expanded ORC type support.
  4. Inspect the file schema with orc-tools to identify the unsupported category.

Example fix

// before
SELECT * FROM iceberg_orc_table -- file has ORC UNION column -> Unhandled type
// after
ALTER/rewrite: cast the union column to a supported primitive and rewrite files
Defensive patterns

Strategy: try-catch

Validate before calling

// check ORC category support before scanning
Set<String> supported = Set.of("BOOLEAN","BYTE","SHORT","INT","LONG","FLOAT","DOUBLE","STRING","VARCHAR","CHAR","BINARY","DECIMAL","DATE","TIMESTAMP");
if (!supported.contains(orcPrimitive.getCategory().getName())) { /* rewrite file */ }

Try / catch

try { reader.read(...); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Unhandled type")) { /* rewrite/convert file */ } throw e; }

Prevention

When it happens

Trigger: Scanning ORC files containing column types outside the supported set (e.g., ORC UNION, unsupported categories) via Iceberg's generic ORC reader.

Common situations: ORC files written by non-Iceberg tools with exotic types; ORC files with union or complex columns where a primitive was expected; corrupt type metadata.

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

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