apache/iceberg · error · UnsupportedOperationException

Altering partition keys is not supported yet.

Error message

Altering partition keys is not supported yet.

What it means

Neither alterTable API currently supports changing a table's partition keys; validateTablePartition compares getPartitionKeys() of the old and new CatalogTable and throws UnsupportedOperationException on any difference. Partition spec changes require rewriting the table, which the alter path does not perform.

Source

Thrown at flink/v2.1/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)

Solutions

1. Keep partition keys unchanged when calling alterTable
2. Drop and recreate the table with the desired partition spec if repartitioning is intended (mind data loss)
3. Perform partition-spec evolution directly on the Iceberg table (updatePartitionSpec) outside the Flink catalog alter API

Example fix

// before
catalog.alterTable(path, tableWithNewPartitionKeys, false);
// after
catalog.alterTable(path, tableWithSamePartitionKeys, false); // or recreate table

if (!existing.getPartitionKeys().equals(newTable.getPartitionKeys())) {
  throw new IllegalStateException("Partition keys cannot be changed via alterTable; recreate the table");
}

null

try { catalog.alterTable(path, newTable, false); } catch (UnsupportedOperationException e) { /* recreate table or use Iceberg updatePartitionSpec */ }

When it happens

Trigger: Calling alterTable with a CatalogTable whose partition keys differ from the existing table's partition keys.

Common situations: Reapplying full DDL where partitioning changed; tooling that regenerates table definitions with a new partition strategy and pushes them through alterTable.

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

• Altering partition keys is not supported yet.
• Namespaces are not supported by catalog:
• Can not alter the default database when the iceberg catalog
• Identity transform is not supported
• Bucket transform is not supported

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