apache/iceberg · error · UnsupportedOperationException

Unsupported to derive Schema for type: ${logicalType}

Error message

Unsupported to derive Schema for type: ${logicalType}

What it means

When converting TIMESTAMP_WITH_LOCAL_TIME_ZONE to an Avro schema with legacyTimestampMapping=true, there is no legacy Avro representation of a zoned timestamp, so the converter throws UnsupportedOperationException("Unsupported to derive Schema for type: " + logicalType) unconditionally, regardless of precision.

Source

Thrown at flink/v1.20/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)

Solutions

1. Set legacyTimestampMapping=false so TIMESTAMP_WITH_LOCAL_TIME_ZONE maps to instant/timestamp-micros logical types.
2. Change the column type to plain TIMESTAMP (without time zone) if the legacy writer must be kept.
3. Convert TIMESTAMP_LTZ columns to TIMESTAMP(3) via CAST in the query before writing.
4. Upgrade downstream Avro consumers that require the legacy mapping before disabling it.

Example fix

// before
Schema s = AvroSchemaConverter.convertToSchema(new LocalZonedTimestampType(3), true); // throws
// after
Schema s = AvroSchemaConverter.convertToSchema(new LocalZonedTimestampType(3), false); // instant logical type

if (legacyTimestampMapping && logicalType instanceof LocalZonedTimestampType) {
  throw new IllegalStateException("TIMESTAMP_LTZ unsupported with legacy mapping; use legacyTimestampMapping=false");
}

try {
  Schema s = AvroSchemaConverter.convertToSchema(ltzType, legacyMapping);
} catch (UnsupportedOperationException e) {
  if (e.getMessage().startsWith("Unsupported to derive Schema for type:")) {
    s = AvroSchemaConverter.convertToSchema(ltzType, false); // switch to non-legacy mapping
  } else throw e;
}

When it happens

Trigger: AvroSchemaConverter.convertToSchema(LogicalType, boolean) — directly or through fieldBuilder on any nested TIMESTAMP_WITH_LOCAL_TIME_ZONE field — while legacyTimestampMapping is true. E.g. a table containing TIMESTAMP_LTZ(3) columns converted with legacy mapping enabled.

Common situations: Legacy timestamp mapping enabled for backward compatibility with old Flink versions while the schema contains local-zoned timestamps introduced in newer Flink; migration of jobs from TIMESTAMP to TIMESTAMP_LTZ without updating the mapping flag.

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

• Unsupported type: ${type}
• Unsupported type: ${type}
• Unsupported type: " + type
• Unsupported type: " + type
• Unsupported to derive Schema for type:

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