What causes "Unknown logical type: {logicalType}" in apache/iceberg?

Remove or convert unsupported logical types in the Avro schema (read the field as its underlying primitive).

apache/iceberg · error · IllegalArgumentException

Unknown logical type: {logicalType}

Error message

Unknown logical type: {logicalType}

What it means

SparkPlannedAvroReader.primitive handles Avro logical types (decimal, uuid, date, timestamp-millis/micros). An Avro schema carrying a logical type outside that set (e.g. time-millis, duration) reaches the default branch and throws IllegalArgumentException.

Source

Thrown at spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/data/SparkPlannedAvroReader.java:162

          case "timestamp-millis":
            // adjust to microseconds
            ValueReader<Long> longs = ValueReaders.longs();
            return (ValueReader<Long>) (decoder, ignored) -> longs.read(decoder, null) * 1000L;

          case "timestamp-micros":
            // Spark uses the same representation
            return ValueReaders.longs();

          case "decimal":
            return SparkValueReaders.decimal(
                ValueReaders.decimalBytesReader(primitive),
                ((LogicalTypes.Decimal) logicalType).getScale());

          case "uuid":
            return SparkValueReaders.uuids();

          default:
            throw new IllegalArgumentException("Unknown logical type: " + logicalType);
        }
      }

      switch (primitive.getType()) {
        case NULL:
          return ValueReaders.nulls();
        case BOOLEAN:
          return ValueReaders.booleans();
        case INT:
          if (partner != null && partner.typeId() == Type.TypeID.LONG) {
            return ValueReaders.intsAsLongs();
          }
          return ValueReaders.ints();
        case LONG:
          return ValueReaders.longs();
        case FLOAT:
          if (partner != null && partner.typeId() == Type.TypeID.DOUBLE) {
            return ValueReaders.floatsAsDoubles();

View on GitHub (pinned to 86d9c8fc54)

Solutions

Remove or convert unsupported logical types in the Avro schema (read the field as its underlying primitive).
Upgrade Iceberg to a version whose Avro reader supports the logical type.
Re-encode the data with standard logical types (e.g. timestamp-micros, decimal).

Defensive patterns

Strategy: validation

Validate before calling

// inspect Avro schema logical types before planning
for (Schema.Field f : avroSchema.getFields()) {
  LogicalType lt = f.schema().getLogicalType();
  Preconditions.checkArgument(
      lt == null || Set.of("decimal","uuid","date","timestamp-millis","timestamp-micros")
          .contains(lt.getName()),
      "Unsupported Avro logical type: %s", lt);}

Prevention

Stick to core Avro logical types when producing data for Iceberg reads
Re-encode files with custom/vendor logical types
Upgrade Iceberg for newer standard logical types

When it happens

Trigger: Planning an Avro read where a field's schema has getLogicalType() returning an unknown logical type name, e.g. Avro 'duration' or custom logical types.

Common situations: Reading Avro files written with newer Avro logical types or vendor-specific logical types unsupported by this Iceberg version.

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/22ba8595b1925012. Report an issue: GitHub.