apache/iceberg · error · UnsupportedOperationException

Unsupported to derive Schema for type: " + logicalType

Error message

Unsupported to derive Schema for type: " + logicalType

What it means

convertToSchema maps Flink LogicalTypes to Avro schemas. TIMESTAMP_WITH_LOCAL_TIME_ZONE has no Avro mapping when legacyTimestampMapping is true (legacy mode only knows local timestamp-millis semantics), so UnsupportedOperationException('Unsupported to derive Schema for type: ...') is thrown.

Solutions

  1. Disable legacy timestamp mapping (legacyTimestampMapping=false) so TIMESTAMP_WITH_LOCAL_TIME_ZONE maps to Avro timestamp-millis/micros logical types.
  2. Change the column type to plain TIMESTAMP (without local time zone) if the legacy path is required.
  3. Convert TIMESTAMP_LTZ values to a supported representation (e.g. BIGINT epoch or TIMESTAMP) upstream.
  4. Align table configuration: the legacy flag and the schema's LTZ columns are mutually incompatible.

Example fix

// before
AvroSchemaConverter.convertToSchema(new LocalZonedTimestampType(3), true)
// after
AvroSchemaConverter.convertToSchema(new LocalZonedTimestampType(3), false)
Defensive patterns

Strategy: validation

Validate before calling

if (logicalType instanceof LocalZonedTimestampType && legacyTimestampMapping) {
  throw new IllegalArgumentException("TIMESTAMP_WITH_LOCAL_TIME_ZONE requires legacyTimestampMapping=false");
}

Try / catch

try { schema = AvroSchemaConverter.convertToSchema(ltzType, legacy); } catch (UnsupportedOperationException e) { /* retry with legacy=false or convert column to TIMESTAMP */ }

Prevention

When it happens

Trigger: Calling convertToSchema (directly or via fieldBuilder) with a LocalZonedTimestampType while legacyTimestampMapping=true.

Common situations: Legacy timestamp compatibility flag enabled (e.g. via table config / SQL legacy options) while the schema contains TIMESTAMP_LTZ columns; old connector configs carried over to newer Flink versions; mixing TZ-aware columns with legacy Avro writers.

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

Appendix: source

Thrown at flink/v2.2/flink/src/main/java/org/apache/iceberg/flink/formats/avro/typeutils/AvroSchemaConverter.java:511

          }
        } else {
          if (precision <= 3) {
            avroLogicalType = LogicalTypes.localTimestampMillis();
          } else if (precision <= 6) {
            avroLogicalType = LogicalTypes.localTimestampMicros();
          } else {
            throw new IllegalArgumentException(
                "Avro does not support LOCAL TIMESTAMP type "
                    + "with precision: "
                    + precision
                    + ", it only supports precision less than 6.");
          }
        }
        Schema timestamp = avroLogicalType.addToSchema(SchemaBuilder.builder().longType());
        return nullable ? nullableSchema(timestamp) : timestamp;
      case TIMESTAMP_WITH_LOCAL_TIME_ZONE:
        if (legacyTimestampMapping) {
          throw new UnsupportedOperationException(
              "Unsupported to derive Schema for type: " + logicalType);
        } else {
          final LocalZonedTimestampType localZonedTimestampType =
              (LocalZonedTimestampType) logicalType;
          precision = localZonedTimestampType.getPrecision();
          if (precision <= 3) {
            avroLogicalType = LogicalTypes.timestampMillis();
          } else if (precision <= 6) {
            avroLogicalType = LogicalTypes.timestampMicros();
          } else {
            throw new IllegalArgumentException(
                "Avro does not support TIMESTAMP type "
                    + "with precision: "
                    + precision
                    + ", it only supports precision less than 6.");
          }
          timestamp = avroLogicalType.addToSchema(SchemaBuilder.builder().longType());
          return nullable ? nullableSchema(timestamp) : timestamp;

View on GitHub (pinned to 86d9c8fc54)