apache/iceberg · error · UnsupportedOperationException

Altering partition keys is not supported yet.

Error message

Altering partition keys is not supported yet.

What it means

FlinkCatalog validates that partition keys are unchanged in both alterTable APIs; partition spec evolution is not implemented for this catalog. If the proposed CatalogTable has different partition keys than the stored table, UnsupportedOperationException is thrown.

Solutions

  1. Drop and recreate the table with the desired partition spec (copy data with INSERT INTO ... SELECT).
  2. Do not alter partition keys; keep the original `PARTITIONED BY` clause when altering properties.
  3. If repartitioning is required, use a new table and migrate data with a batch job.

Example fix

// before
sql("ALTER TABLE iceberg_db.t SET ('key'='v') PARTITIONED BY (dt)");

// after
sql("ALTER TABLE iceberg_db.t SET ('key'='v')"); // keep partition spec unchanged
Defensive patterns

Strategy: validation

Validate before calling

// ensure partition keys are unchanged
if (!oldCt.getPartitionKeys().equals(newCt.getPartitionKeys())) {
  throw new IllegalArgumentException("partition keys must remain unchanged; recreate the table instead");
}

Try / catch

try {
  catalog.alterTable(tablePath, ct, false);
} catch (UnsupportedOperationException e) {
  // handle partition-change attempt: recreate table or keep original spec
}

Prevention

When it happens

Trigger: Calling either `alterTable(tablePath, ct, ignoreIfNotExists)` or `alterTable(tablePath, changes, ignoreIfNotExists)` where `ct.getPartitionKeys()` differs from the current table's partition keys (Flink path rebuilds and compares), e.g. changing `PARTITIONED BY (a)` to `PARTITIONED BY (a, b)` on an existing Iceberg table.

Common situations: Running Flink SQL `ALTER TABLE ... SET PARTITIONED BY` or re-creating DDL with modified PARTITIONED BY clause and applying it through the catalog; migration scripts that carry modified partitioning.

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

Appendix: source

Thrown at flink/v2.2/flink/src/main/java/org/apache/iceberg/flink/FlinkCatalog.java:488

  private boolean isReservedProperty(String prop) {
    return FlinkCreateTableOptions.LOCATION_KEY.equalsIgnoreCase(prop)
        || FlinkCreateTableOptions.CONNECTOR_PROPS_KEY.equalsIgnoreCase(prop)
        || FlinkCreateTableOptions.SRC_CATALOG_PROPS_KEY.equalsIgnoreCase(prop);
  }

  private static void validateTableSchemaAndPartition(CatalogTable ct1, CatalogTable ct2) {
    if (!Objects.equals(ct1.getUnresolvedSchema(), ct2.getUnresolvedSchema())) {
      throw new UnsupportedOperationException(
          "Altering schema is not supported in the old alterTable API. "
              + "To alter schema, use the other alterTable API and provide a list of TableChange's.");
    }

    validateTablePartition(ct1, ct2);
  }

  private static void validateTablePartition(CatalogTable ct1, CatalogTable ct2) {
    if (!ct1.getPartitionKeys().equals(ct2.getPartitionKeys())) {
      throw new UnsupportedOperationException("Altering partition keys is not supported yet.");
    }
  }

  /**
   * This alterTable API only supports altering table properties.
   *
   * <p>Support for adding/removing/renaming columns cannot be done by comparing CatalogTable
   * instances, unless the Flink schema contains Iceberg column IDs.
   *
   * <p>To alter columns, use the other alterTable API and provide a list of TableChange's.
   *
   * @param tablePath path of the table or view to be modified
   * @param newTable the new table definition
   * @param ignoreIfNotExists flag to specify behavior when the table or view does not exist: if set
   *     to false, throw an exception, if set to true, do nothing.
   * @throws CatalogException in case of any runtime exception
   * @throws TableNotExistException if the table does not exist
   */

View on GitHub (pinned to 86d9c8fc54)