apache/iceberg · error · java.lang.UnsupportedOperationException

Unsupported logical type:

Error message

Unsupported logical type:

What it means

In FlinkParquetWriters, primitive(...) first asks LogicalTypeWriterBuilder (a LogicalTypeAnnotationVisitor) to handle columns carrying a Parquet logical type annotation. If the annotation is present but visit() returns Optional.empty() — i.e. the annotation is not one the writer builder knows — the code throws UnsupportedOperationException naming the original Parquet type.

Source

Thrown at flink/v2.3/flink/src/main/java/org/apache/iceberg/flink/data/FlinkParquetWriters.java:193

    }

    private ParquetValueWriter<?> newOption(Type fieldType, ParquetValueWriter<?> writer) {
      int maxD = type.getMaxDefinitionLevel(path(fieldType.getName()));
      return ParquetValueWriters.option(fieldType, maxD, writer);
    }

    @Override
    public ParquetValueWriter<?> primitive(LogicalType fType, PrimitiveType primitive) {
      ColumnDescriptor desc = type.getColumnDescription(currentPath());

      LogicalTypeAnnotation annotation = primitive.getLogicalTypeAnnotation();
      if (annotation != null) {
        Optional<ParquetValueWriter<?>> writer =
            annotation.accept(new LogicalTypeWriterBuilder(fType, desc));
        if (writer.isPresent()) {
          return writer.get();
        } else {
          throw new UnsupportedOperationException(
              "Unsupported logical type: " + primitive.getOriginalType());
        }
      }

      switch (primitive.getPrimitiveTypeName()) {
        case FIXED_LEN_BYTE_ARRAY:
        case BINARY:
          return byteArrays(desc);
        case BOOLEAN:
          return ParquetValueWriters.booleans(desc);
        case INT32:
          return ints(fType, desc);
        case INT64:
          return ParquetValueWriters.longs(desc);
        case FLOAT:
          return ParquetValueWriters.floats(desc);
        case DOUBLE:
          return ParquetValueWriters.doubles(desc);

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Inspect the file schema (parquet-tools/meta) to identify the offending annotation on the column.
  2. Adjust the write schema so the column uses a supported annotated type (e.g. standard decimal, timestamp, string/uuid-style annotations Iceberg supports).
  3. If the annotation should be supported, add a visit(...) case to LogicalTypeWriterBuilder and return an appropriate writer.

Example fix

// before: column annotated as ENUM (unsupported by visitor)
// after: write the column as a plain required/optional BINARY or STRING type
Defensive patterns

Strategy: validation

Validate before calling

// java
LogicalTypeAnnotation ann = column.getPrimitiveType().getLogicalTypeAnnotation();
boolean supported = ann == null || ann.accept(new LogicalTypeAnnotationVisitor<Boolean>() {
  public Optional<Boolean> visit(DecimalLogicalTypeAnnotation d) { return Optional.of(true); }
  public Optional<Boolean> visit(TimestampLogicalTypeAnnotation t) { return Optional.of(true); }
  // return Optional.empty() for anything else
});

Try / catch

// java
try {
  writer = FlinkParquetWriters.write(compatibleSchema, rowType, outputFactory);
} catch (UnsupportedOperationException e) {
  throw new IllegalStateException("Column uses unsupported Parquet logical type; fix write schema", e);
}

Prevention

When it happens

Trigger: Writing Flink data to Parquet where a column's Parquet type has a logical annotation that LogicalTypeWriterBuilder does not implement (e.g. less common annotations like ENUM, JSON, BSON, INTERVAL, or unknown/future annotations).

Common situations: Schema converted from a source format that produced exotic Parquet logical types; newer Parquet annotation types written by other engines; mis-mapped Flink types that yielded unexpected annotations.

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

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