apache/iceberg · error · java.lang.UnsupportedOperationException

Altering partition keys is not supported yet.

Error message

Altering partition keys is not supported yet.

What it means

FlinkCatalog does not support changing a table's partition keys. validateTablePartition compares the partition keys of the existing and replacement CatalogTable in the legacy alterTable path and throws UnsupportedOperationException if they differ. Partitioning is fixed at table creation in Iceberg via its PartitionSpec.

Source

Thrown at flink/v1.20/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. Drop and recreate the table with the desired partition spec (migrating data), since Iceberg cannot alter partitioning in place.
2. Keep partition keys identical and only change properties through the alterTable path.
3. Use Flink/Iceberg rewrite-datafiles or migration tooling (e.g. Iceberg's stored-procedure/rewrite workflow in a Spark engine) to change layout instead of altering partition keys.

Example fix

// before
catalog.alterTable(path, tableWithNewPartitionKeys, false);
// after
// recreate instead:
catalog.dropTable(path, false);
catalog.createTable(path, tableWithNewPartitionKeys);

if (!current.getPartitionKeys().equals(proposed.getPartitionKeys())) {
  throw new IllegalArgumentException("Recreate the table to change partitioning");
}

boolean partitionKeysUnchanged(CatalogTable a, CatalogTable b) {
  return a.getPartitionKeys().equals(b.getPartitionKeys());
}

try { catalog.alterTable(path, proposed, false); }
catch (UnsupportedOperationException e) { /* plan drop+recreate migration instead */ }

When it happens

Trigger: Calling legacy alterTable(tablePath, catalogTable, ignoreIfNotExists) where the new CatalogTable's getPartitionKeys() list differs from the current table's — adding, removing, or reordering partition columns.

Common situations: Trying to repartition an existing table via full CatalogTable replacement; DDL generators that always emit partition keys; copying a table definition with different partitioning onto an existing table.

Related errors

• Altering partition keys is not supported yet.
• Unsupported table change: AddWatermark.
• Unsupported table change: ModifyWatermark.
• Unsupported table change: DropWatermark.
• Identity transform is not supported

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