apache/iceberg · error · IllegalArgumentException

Unhandled type

Error message

Unhandled type 

What it means

SparkOrcWriter.primitive maps Iceberg primitive types to ORC value writers. All standard primitives are covered in the switch; the default branch should be unreachable and fires only for an unrecognized primitive. This IllegalArgumentException means a type in the Iceberg schema could not be translated into an ORC writer during a Spark write.

Source

Thrown at spark/v3.5/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 the Iceberg Spark runtime so the writer supports the type.
2. Change the schema column to a supported primitive type.
3. Align writer and reader Iceberg versions across jobs.
4. Validate the table schema before writing.

// Ensure table schema types are all standard Iceberg primitives before writing via Spark ORC
table.schema().columns().forEach(f -> {
  if (f.type().isPrimitiveType() && f.type().typeId() == org.apache.iceberg.types.Type.TypeID.UNKNOWN) {
    throw new IllegalStateException("Unsupported primitive in schema: " + f.name());
  }
});

try {
  df.write().format("iceberg").mode("append").save(tableLocation);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Unhandled type")) {
    // inspect schema and migrate column types
  } else throw e;
}

When it happens

Trigger: Writing Spark data whose Iceberg schema contains a primitive type with no writer mapping (unexpected type reaching default, e.g. unknown/future type ids not covered by the switch).

Common situations: Version skew where a table schema uses a type introduced in a newer spec than the writer supports; programmatic schema construction with invalid types.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Encountered an unsupported ORC type during a write from Spar
• Unhandled type {primitive}
• 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/d3000ee489121b65. Report an issue: GitHub.