apache/iceberg · error · IllegalArgumentException

Unhandled type {primitive}

Error message

Unhandled type {primitive}

What it means

SparkOrcWriter.primitive() maps Iceberg primitive types to ORC value writers; the default branch throws IllegalArgumentException for any primitive outside the handled set (BOOLEAN..DECIMAL, TIMESTAMP*, DATE, BINARY, etc.). This guards against writing Iceberg types that have no ORC representation in this writer path.

Source

Thrown at spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/data/SparkOrcWriter.java:130

          return GenericOrcWriters.floats(ORCSchemaUtil.fieldId(primitive));
        case DOUBLE:
          return GenericOrcWriters.doubles(ORCSchemaUtil.fieldId(primitive));
        case BINARY:
          if (Type.TypeID.UUID == iPrimitive.typeId()) {
            return SparkOrcValueWriters.uuids();
          }
          return GenericOrcWriters.byteArrays();
        case STRING:
        case CHAR:
        case VARCHAR:
          return SparkOrcValueWriters.strings();
        case DECIMAL:
          return SparkOrcValueWriters.decimal(primitive.getPrecision(), primitive.getScale());
        case TIMESTAMP_INSTANT:
        case TIMESTAMP:
          return SparkOrcValueWriters.timestampTz();
        default:
          throw new IllegalArgumentException("Unhandled type " + primitive);
      }
    }
  }

  private static class InternalRowWriter extends GenericOrcWriters.StructWriter<InternalRow> {
    private final List<FieldGetter<?>> fieldGetters;

    InternalRowWriter(
        List<OrcValueWriter<?>> writers, Types.StructType iStruct, List<TypeDescription> orcTypes) {
      super(iStruct, writers);
      this.fieldGetters = Lists.newArrayListWithExpectedSize(orcTypes.size());

      Map<Integer, TypeDescription> idToType =
          orcTypes.stream().collect(Collectors.toMap(ORCSchemaUtil::fieldId, s -> s));

      for (Types.NestedField iField : iStruct.fields()) {
        fieldGetters.add(createFieldGetter(idToType.get(iField.fieldId())));
      }

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Upgrade Iceberg to a version whose SparkOrcWriter supports the type
2. Exclude or cast the unsupported column before writing (e.g. store uuid as fixed(len) bytes or string)
3. Use Parquet instead of ORC for tables using uuid/variant columns
4. Check SparkOrcWriter.primitive() for the supported type list

Example fix

// before
table.updateSchema().addColumn("id", Types.UUIDType.get()).commit()
// after (ORC path)
table.updateSchema().addColumn("id", Types.StringType.get()).commit()

table.schema().columns().forEach(c -> {
  Type.TypeID id = c.type().typeId();
  Set<Type.TypeID> supported = Set.of(Type.TypeID.BOOLEAN, Type.TypeID.INTEGER, Type.TypeID.LONG,
      Type.TypeID.FLOAT, Type.TypeID.DOUBLE, Type.TypeID.DATE, Type.TypeID.TIME, Type.TypeID.TIMESTAMP,
      Type.TypeID.STRING, Type.TypeID.UUID, Type.TypeID.DECIMAL, Type.TypeID.BINARY);
  if (!supported.contains(id)) {
    throw new IllegalStateException("Type not writable to ORC via SparkOrcWriter: " + c.type());
  }
});

boolean orcWritable(Type t) {
  return Set.of(Type.TypeID.BOOLEAN, Type.TypeID.INTEGER, Type.TypeID.LONG, Type.TypeID.FLOAT,
      Type.TypeID.DOUBLE, Type.TypeID.DATE, Type.TypeID.TIME, Type.TypeID.TIMESTAMP,
      Type.TypeID.STRING, Type.TypeID.DECIMAL, Type.TypeID.BINARY).contains(t.typeId());
}

try {
  writer.write(row);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Unhandled type")) { /* cast the column or switch file format */ }
  else throw e;
}

When it happens

Trigger: Writing a table whose schema contains a primitive type the ORC writer does not map — e.g. UUID or variant via a Spark ORC write path that lacks those cases.

Common situations: Writing tables with Iceberg v3 types (uuid, variant) through the Spark ORC data writer; version gaps where the type was added to the spec but not the ORC writer; schema evolution adding new column types.

Related errors

• Unhandled type
• Encountered an unsupported ORC type during a write from Spar
• Invalid iceberg type %s corresponding to ORC type %s
• Unhandled type
• Expected one (and same) ORC type for list elements, got:

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