apache/iceberg · error · IllegalArgumentException

Unhandled type

Error message

Unhandled type

What it means

SparkOrcReader.primitive maps Iceberg/ORC primitive types to ORC value readers. Covered cases include all standard types plus UUID via BINARY; the default branch throws for any primitive the reader does not handle. This IllegalArgumentException means an Iceberg type in the schema could not be translated into an ORC reader during a Spark read.

Source

Thrown at spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/data/SparkOrcReader.java:131

          return OrcValueReaders.floats();
        case DOUBLE:
          return OrcValueReaders.doubles();
        case TIMESTAMP_INSTANT:
        case TIMESTAMP:
          return SparkOrcValueReaders.timestampTzs();
        case DECIMAL:
          return SparkOrcValueReaders.decimals(primitive.getPrecision(), primitive.getScale());
        case CHAR:
        case VARCHAR:
        case STRING:
          return SparkOrcValueReaders.utf8String();
        case BINARY:
          if (Type.TypeID.UUID == iPrimitive.typeId()) {
            return SparkOrcValueReaders.uuids();
          }
          return OrcValueReaders.bytes();
        default:
          throw new IllegalArgumentException("Unhandled type " + primitive);
      }
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Upgrade the Iceberg Spark runtime so the reader supports the type.
  2. Rewrite the table with supported types (e.g. store uuid as binary if on an old reader).
  3. Check the table schema for unusual types and map them to supported primitives.
  4. Ensure writer and reader Iceberg versions are aligned.

Example fix

// before: table column of unsupported type
// after: alter/rewrite schema to a supported type, e.g.
ALTER TABLE t ALTER COLUMN u SET // uuid supported in newer versions; otherwise use binary
Defensive patterns

Strategy: validation

Validate before calling

// Check the table schema for types the Spark ORC reader may not handle before scanning
for (org.apache.iceberg.types.Types.NestedField f : table.schema().columns()) {
  if (f.type().typeId() == org.apache.iceberg.types.Type.TypeID.UUID) {
    // ensure your Iceberg Spark runtime supports uuid in ORC reads
  }
}

Try / catch

try {
  spark.read().format("iceberg").load("db.t").collect();
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Unhandled type")) {
    // fall back: upgrade runtime or read a rewritten table
  } else throw e;
}

Prevention

When it happens

Trigger: Reading an ORC file whose Iceberg schema includes a primitive type with no reader mapping (e.g. an unexpected type reaching the default case such as an unknown/future type id in a BINARY-less position or a type the Spark ORC reader does not support).

Common situations: Reading tables written by newer Iceberg versions or other engines that use types this Spark reader version does not understand; version-skew between writer and reader.

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