apache/iceberg · error · UnsupportedOperationException

Month transform is not supported

Error message

Month transform is not supported

What it means

PartitionSpecVisitor's default month() methods throw UnsupportedOperationException to signal that the concrete visitor does not handle partition fields using the month temporal transform. When PartitionSpecVisitor.visit encounters a field transformed by Dates.MONTH, Timestamps.MICROS_TO_MONTH/NANOS_TO_MONTH, or an instance of Months, it dispatches to month(); an implementation that skipped this override hits the throwing default. This fail-fast prevents silently mis-translating partition specs.

Source

Thrown at api/src/main/java/org/apache/iceberg/transforms/PartitionSpecVisitor.java:65

  default T truncate(String sourceName, int sourceId, int width) {
    throw new UnsupportedOperationException("Truncate transform is not supported");
  }

  default T year(int fieldId, String sourceName, int sourceId) {
    return year(sourceName, sourceId);
  }

  default T year(String sourceName, int sourceId) {
    throw new UnsupportedOperationException("Year transform is not supported");
  }

  default T month(int fieldId, String sourceName, int sourceId) {
    return month(sourceName, sourceId);
  }

  default T month(String sourceName, int sourceId) {
    throw new UnsupportedOperationException("Month transform is not supported");
  }

  default T day(int fieldId, String sourceName, int sourceId) {
    return day(sourceName, sourceId);
  }

  default T day(String sourceName, int sourceId) {
    throw new UnsupportedOperationException("Day transform is not supported");
  }

  default T hour(int fieldId, String sourceName, int sourceId) {
    return hour(sourceName, sourceId);
  }

  default T hour(String sourceName, int sourceId) {
    throw new UnsupportedOperationException("Hour transform is not supported");
  }

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Override month(int fieldId, String sourceName, int sourceId) in your visitor to translate the month transform correctly
  2. Pre-validate the partition spec's partitionType() to detect month transforms before invoking the visitor
  3. If month partitioning is genuinely unsupported in your target, override month() to raise a clear domain error or skip the field explicitly

Example fix

// before
@Override
public String identity(int fieldId, String sourceName, int sourceId) { return sourceName; }
// month transform falls through to throwing default
// after
@Override
public String month(int fieldId, String sourceName, int sourceId) {
  return "months(" + sourceName + ")";
}
Defensive patterns

Strategy: validation

Validate before calling

boolean hasMonthTransform(PartitionSpec spec) {
  return spec.fields().stream().anyMatch(f -> f.transform() instanceof Months
      || f.transform() == Dates.MONTH || f.transform() == Timestamps.MICROS_TO_MONTH);
}
// run before visit(); reject or add a month() override first

Type guard

if (field.transform() instanceof Months) {
  throw new IllegalStateException("Visitor does not support month transform: " + field);
}

Try / catch

try {
  PartitionSpecVisitor.visit(spec, visitor);
} catch (UnsupportedOperationException e) {
  LOG.error("Visitor missing month-transform support for spec {}", spec, e);
  throw e;
}

Prevention

When it happens

Trigger: PartitionSpecVisitor.visit on a table partitioned with month(date_col) or month(ts_col) where the visitor implementation lacks a month(int, String, int) or month(String, int) override.

Common situations: Custom catalog-integration visitors (Hive metastore, JDBC, Nessie translators) that handle identity/bucket/truncate but not temporal transforms; applying a visitor written for a different table to one partitioned by month.

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