apache/iceberg · error · java.lang.IllegalArgumentException

Unknown logical type: ${logicalType.getName()}

Error message

Unknown logical type: ${logicalType.getName()}

What it means

FlinkPlannedAvroReader.primitive maps Avro logical types (date, time-micros, timestamp-micros, decimal, uuid) to Flink value readers. When a primitive has a logical type whose name is not among the supported set, the library throws this IllegalArgumentException. It means the Avro file uses a logical type the reader does not recognize.

Source

Thrown at flink/v2.1/flink/src/main/java/org/apache/iceberg/flink/data/FlinkPlannedAvroReader.java:166

          case "timestamp-micros":
            return FlinkValueReaders.timestampMicros();

          case "timestamp-nanos":
            return FlinkValueReaders.timestampNanos();

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

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

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

      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. Identify the logical type via the Avro schema and remove/replace it with a supported one (date, time-micros, timestamp-micros, decimal, uuid)
2. Convert the field to its raw primitive (e.g. write it as long/int/string without a logical type) in the producer
3. Upgrade Iceberg to a version that supports the logical type, or add a case in FlinkPlannedAvroReader.primitive

Example fix

// before (producer schema)
{"type":"long","logicalType":"time-millis"}
// after
{"type":"int","logicalType":"time-micros"}

Set<String> supported = Set.of("date","time-micros","timestamp-micros","decimal","uuid");
for (Schema.Field f : schema.getFields()) {
  Schema s = f.schema().getTypes().size() == 1 ? f.schema() : f.schema().getTypes().get(1);
  if (s.getLogicalType() != null && !supported.contains(s.getLogicalType().getName())) {
    throw new IllegalArgumentException("Unsupported logical type: " + s.getLogicalType().getName());
  }
}

boolean isSupportedLogical(Schema s) {
  return s.getLogicalType() == null || Set.of("date","time-micros","timestamp-micros","decimal","uuid").contains(s.getLogicalType().getName());
}

try { reader = FlinkPlannedAvroReader.create(...); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Unknown logical type")) { /* fall back to raw-type reader */ } else throw e; }

When it happens

Trigger: Reading Avro data containing a primitive with an unrecognized logical type name such as time-millis, timestamp-millis, local-timestamp-micros, or a vendor-specific logical type, via FlinkPlannedAvroReader.

Common situations: Avro files written by other systems (Kafka Connect, Confluent serializers) using logical types Iceberg's Flink reader doesn't handle; schema evolution introducing newer logical types.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Unknown logical type:
• Unknown logical type:
• Unknown logical type: ${logicalType.getName()}
• Unsupported logical type:
• Unknown logical type: " + logicalType.getName()

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