apache/iceberg · error · IllegalArgumentException
Unhandled type {primitive}
Error message
Unhandled type {primitive} What it means
SparkOrcReader maps Iceberg types to ORC value readers. The default branch of primitive() throws IllegalArgumentException for ORC primitive types it has no reader for (outside the handled BOOLEAN, BYTE, SHORT, INT, LONG, FLOAT, DOUBLE, STRING, VARCHAR, CHAR, DECIMAL, TIMESTAMP, TIMESTAMP_INSTANT, DATE, BINARY cases). It signals an ORC file whose column type cannot be read into the requested Iceberg type.
Source
Thrown at spark/v4.1/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 Iceberg to a version with broader ORC type support
- Rewrite/re-export the ORC file with supported types
- Verify the expected Iceberg type matches the ORC column type
- Cast the column to a supported type in the producing pipeline
Defensive patterns
Strategy: try-catch
Validate before calling
for (TypeDescription child : orcFileSchema.getChildren()) {
if (child.getCategory().isPrimitive() && !SUPPORTED.contains(child.getCategory())) {
throw new IllegalStateException("ORC type not readable: " + child);
}
} Try / catch
try {
CloseableIterable<SparkInternalRow> rows = reader.read();
} catch (IllegalArgumentException e) {
if (e.getMessage().startsWith("Unhandled type")) { /* rewrite the ORC file or upgrade */ }
else throw e;
} Prevention
- Write ORC files with standard ORC types
- Keep Iceberg updated for new ORC category support
- Validate Iceberg-to-ORC type mapping before bulk reads
When it happens
Trigger: Reading an ORC file containing a primitive type not handled by the switch, e.g. uncommon ORC types like union or unsupported temporal variants, when mapping to the expected Iceberg type.
Common situations: ORC files written by other tools with unusual type usage; version mismatch where new ORC types exist but reader mapping is missing; type mapping mismatches during schema evolution.
Understand the failure class
Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.
Related errors
AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12).
Data as JSON: /api/errors/451d7c228de28e52.
Report an issue: GitHub.