apache/iceberg · error · java.lang.IllegalArgumentException

Unknown logical type: ${logicalType}

Error message

Unknown logical type: ${logicalType}

What it means

The Iceberg Spark planned Avro reader throws IllegalArgumentException when an Avro schema field carries a logical type (e.g. decimal, uuid, date variants) that it does not recognize. The reader only maps the logical types in its switch (string, decimal, uuid, etc.); anything else is treated as an unsupported schema and fails fast instead of silently misreading data.

Source

Thrown at spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/data/SparkPlannedAvroReader.java:156

          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

  1. Upgrade the Iceberg runtime to a version whose Avro reader supports the logical type in question
  2. Rewrite/export the data with standard or no logical types (plain bytes/long/string)
  3. Inspect the Avro schema of the failing field (avro-tools getschema) to identify the unsupported logicalType
  4. Remove or convert the exotic logical type in the producing pipeline

Example fix

// before: producer writes fields with custom logicalType "my-money"
// after: use a standard logical type or none
{"name":"amount","type":{"type":"bytes","logicalType":"decimal","precision":38,"scale":10}}
Defensive patterns

Strategy: validation

Validate before calling

import org.apache.avro.Schema;
boolean supported(Schema.Field f) {
  Schema s = f.schema();
  String lt = s.getLogicalType() != null ? s.getLogicalType().getName() : null;
  return lt == null || lt.equals("decimal") || lt.equals("uuid") || lt.equals("string")
      || lt.equals("date") || lt.equals("timestamp-millis") || lt.equals("timestamp-micros");
}

Try / catch

try {
  reader.read();
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Unknown logical type:")) {
    // re-export data with standard logical types or upgrade Iceberg
  } else throw e;
}

Prevention

When it happens

Trigger: Reading Avro data files (e.g. Avro-based manifest data or Avro table reads) where a field's Avro schema declares a logicalType not in the reader's supported set — for example custom/proprietary logical types, or Avro logical types added in newer Avro specs (duration, time-micros in some configurations).

Common situations: Data produced by writers using nonstandard Avro logical types; schema evolution introducing a new logical type while the Iceberg runtime is older; hand-authored Avro schemas in tests.

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