What causes "Unsupported logical type: %s" in apache/iceberg?

Check which logical type triggered it from the message and remove/retype the column (e.g. store as string/bytes without the annotation).

apache/iceberg · error · java.lang.IllegalArgumentException

Unsupported logical type: %s

Error message

Unsupported logical type: %s

What it means

FlinkAvroWriter.primitive() throws IllegalArgumentException 'Unsupported logical type: <type>' when an Iceberg primitive type carries a logical type annotation (e.g. a uuid string logical type) that the Avro writer builder does not recognize. Only a fixed set of logical types (decimal, uuid per some writers) is supported; anything else falls through to the default branch.

Source

Thrown at flink/v2.1/flink/src/main/java/org/apache/iceberg/flink/data/FlinkAvroWriter.java:144

          case "time-micros":
            return FlinkValueWriters.timeMicros();

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

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

          case "decimal":
            LogicalTypes.Decimal decimal = (LogicalTypes.Decimal) logicalType;
            return FlinkValueWriters.decimal(decimal.getPrecision(), decimal.getScale());

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

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

      switch (primitive.getType()) {
        case NULL:
          return ValueWriters.nulls();
        case BOOLEAN:
          return ValueWriters.booleans();
        case INT:
          switch (type.getTypeRoot()) {
            case TINYINT:
              return ValueWriters.tinyints();
            case SMALLINT:
              return ValueWriters.shorts();
            default:
              return ValueWriters.ints();
          }
        case LONG:

View on GitHub (pinned to 86d9c8fc54)

Solutions

Check which logical type triggered it from the message and remove/retype the column (e.g. store as string/bytes without the annotation).
Upgrade iceberg-flink to a newer version where the logical type may be supported.
File/consult an issue for adding support for the logical type in FlinkValueWriters.
Convert data before writing: project the table to a schema without the unsupported logical type via TableScan.withProjection or select().

Example fix

// before
Types.NestedField field = Types.NestedField.optional(1, "id", Types.UUIDType.get());
// after (if unsupported by writer version)
Types.NestedField field = Types.NestedField.optional(1, "id", Types.StringType.get());

Defensive patterns

Strategy: validation

Validate before calling

schema.columns().forEach(c -> {
  if (c.type() instanceof Types.UUIDType || hasLogicalAnnotation(c.type())) {
    // ensure writer version supports it or retype
  }
});

Type guard

boolean isSupportedPrimitive(Type t) {
  return t.typeId() == Type.TypeID.BOOLEAN || t.typeId() == Type.TypeID.INTEGER
    || t.typeId() == Type.TypeID.LONG || t.typeId() == Type.TypeID.FLOAT
    || t.typeId() == Type.TypeID.DOUBLE || t.typeId() == Type.TypeID.STRING
    || t.typeId() == Type.TypeID.BINARY || t.typeId() == Type.TypeID.FIXED
    || t.typeId() == Type.TypeID.DATE || t.typeId() == Type.TypeID.TIMESTAMP
    || t.typeId() == Type.TypeID.DECIMAL;
}

Try / catch

try {
  writer.write(rowData);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Unsupported logical type")) {
    throw new IllegalStateException("Retype or upgrade writer for: " + e.getMessage(), e);
  }
  throw e;
}

Prevention

Prefer string columns over uuid unless your writer version supports it.
Check the flink writer's supported logical types before adopting new Iceberg types.
Pin schema definitions in one place and validate against writer support.

When it happens

Trigger: Writing an Iceberg table containing a primitive column with an Avro logical-type annotation not handled by the switch (e.g. an unexpected/unknown logical type annotation) to Avro files.

Common situations: Tables written by newer Iceberg versions or other engines introducing logical types the Flink v2.1 Avro writer doesn't support; custom type mappings.

Related errors

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