What causes "Unhandled type ${primitive}" in apache/iceberg?

Identify the offending column type from the message and disable vectorization for that read (read.vectorization.enabled=false).

apache/iceberg · error · java.lang.IllegalArgumentException

Unhandled type

Error message

Unhandled type ${primitive}

What it means

VectorizedSparkOrcReaders maps Iceberg primitive types to ORC value readers for the vectorized ORC path. The switch over the primitive's type id has no reader for the encountered type, so it hits the default branch and throws IllegalArgumentException. This means the Iceberg type has no vectorized ORC reader implementation in this version.

Solutions

Identify the offending column type from the message and disable vectorization for that read (read.vectorization.enabled=false).
Upgrade Iceberg to a version whose VectorizedSparkOrcReaders supports the type (e.g. UUID support was added later).
Recreate/rewrite the table with a supported type (e.g. store UUID as fixed(16) or string) if an upgrade is not possible.
If you maintain the code, add a case for the missing TypeID mapping to an appropriate OrcValueReader.

Defensive patterns

Strategy: fallback

Validate before calling

boolean unsupported = schema.columns().stream()
    .anyMatch(c -> c.type().typeId() == Type.TypeID.UUID);
if (unsupported && format.equals("orc")) { spark.conf.set("read.vectorization.enabled", "false"); }

Try / catch

try {
  orcScan = VectorizedSparkOrcReaders.reader(...);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Unhandled type")) { useBatchReaderInstead(); } else throw e;
}

Prevention

Before enabling vectorized ORC reads, confirm all schema types are covered by your Iceberg version.
Upgrade Iceberg when reading ORC tables with newer types like UUID.
Set read.vectorization.enabled=false at table level for tables with exotic types.

When it happens

Trigger: Running a vectorized ORC scan over a table whose schema contains a primitive type not handled by the switch — commonly types like uuid, variant, unknown future types, or nested-in-list/map primitives the reader doesn't cover.

Common situations: Reading ORC tables written by newer Iceberg versions (e.g. with UUID columns) using an older runtime; tables whose schemas evolved to include types the vectorized ORC reader predates; misconfigured vectorization over exotic types.

Related errors

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

Appendix: source

Thrown at spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/data/vectorized/VectorizedSparkOrcReaders.java:164

          primitiveValueReader = SparkOrcValueReaders.timestampTzs();
          break;
        case DECIMAL:
          primitiveValueReader =
              SparkOrcValueReaders.decimals(primitive.getPrecision(), primitive.getScale());
          break;
        case CHAR:
        case VARCHAR:
        case STRING:
          primitiveValueReader = SparkOrcValueReaders.utf8String();
          break;
        case BINARY:
          primitiveValueReader =
              Type.TypeID.UUID == iPrimitive.typeId()
                  ? SparkOrcValueReaders.uuids()
                  : OrcValueReaders.bytes();
          break;
        default:
          throw new IllegalArgumentException("Unhandled type " + primitive);
      }
      return (columnVector, batchSize, batchOffsetInFile, isSelectedInUse, selected) ->
          new PrimitiveOrcColumnVector(
              iPrimitive, batchSize, columnVector, primitiveValueReader, isSelectedInUse, selected);
    }
  }

  private abstract static class BaseOrcColumnVector extends ColumnVector {
    private final org.apache.orc.storage.ql.exec.vector.ColumnVector vector;
    private final int batchSize;
    private final boolean isSelectedInUse;
    private final int[] selected;
    private Integer numNulls;

    BaseOrcColumnVector(
        Type type,
        int batchSize,
        org.apache.orc.storage.ql.exec.vector.ColumnVector vector,

View on GitHub (pinned to 86d9c8fc54)