apache/iceberg · error · IllegalArgumentException
Unhandled type
Error message
Unhandled type
What it means
SparkOrcReader.primitive maps ORC primitive types to Spark ORC value readers; the switch ends in a default that throws IllegalArgumentException('Unhandled type ' + primitive). It means an ORC primitive appeared that the reader has no Spark mapping for.
Source
Thrown at spark/v4.0/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
- Upgrade the Iceberg runtime to a version handling the ORC primitive type
- Rewrite/convert the ORC data to Iceberg-supported types
- Exclude the unsupported column from the read projection
- Check the exception message to identify the exact unhandled ORC type
Example fix
// before
spark.read.format("iceberg").load("table") // file has unhandled ORC primitive
// after: upgrade runtime or exclude/retype the column
df = spark.read.format("iceberg").load("table").select("supported_col"); Defensive patterns
Strategy: validation
Validate before calling
// check ORC schema before reading
TypeDescription schema = reader.getSchema();
schema.getChildren().forEach(c -> {
Preconditions.checkArgument(isSupported(c.getCategory()), "Unhandled ORC type: " + c.getCategory());
}); Try / catch
try { spark.read.format("iceberg").load("table"); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Unhandled type ")) { /* upgrade or exclude column */ } else { throw e; } } Prevention
- Write ORC data using Iceberg-supported types only
- Keep the runtime version aligned with ORC writers
- Inspect ORC file schemas for exotic types before ingesting
When it happens
Trigger: Reading an ORC file whose declared primitive type isn't handled by the reader's switch — typically exotic/unsupported ORC types or ORC files written with types outside Iceberg's supported set.
Common situations: ORC files written by external tools using ORC types Iceberg doesn't map; mixed-version runtimes where a newer ORC type was written but the read path is older; corrupted schema descriptors.
Understand the failure class
Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.
Related errors
AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12).
Data as JSON: /api/errors/5601a8d8fdc21d77.
Report an issue: GitHub.