apache/iceberg · error · UnsupportedOperationException

Altering partition keys is not supported yet.

Error message

Altering partition keys is not supported yet.

What it means

An UnsupportedOperationException from validateTablePartition thrown when an alterTable attempt changes the table's partition keys. Iceberg tables in this Flink catalog do not support altering partitioning via alterTable.

Solutions

  1. Do not change partition keys via alterTable; keep the partition spec unchanged.
  2. To change partitioning, create a new table with the desired spec and migrate data (e.g. INSERT INTO ... SELECT), or evolve the partition spec using Iceberg's core API outside this Flink catalog path.
  3. Verify the replacement CatalogTable preserves ct.getPartitionKeys().equals(existing.getPartitionKeys()).

Example fix

// before
CatalogTable newTable = new CatalogTableImpl(schema, Collections.singletonList("dt"), props, "");
flinkCatalog.alterTable(path, newTable, false);
// after
CatalogTable newTable = new CatalogTableImpl(schema, oldTable.getPartitionKeys(), props, "");
flinkCatalog.alterTable(path, newTable, false);
Defensive patterns

Strategy: validation

Validate before calling

if (!newTable.getPartitionKeys().equals(oldTable.getPartitionKeys())) {
  throw new IllegalArgumentException("partition keys must remain unchanged");
}

Prevention

When it happens

Trigger: Calling alterTable (legacy or TableChange-based, which also calls validateTablePartition) with a CatalogTable whose getPartitionKeys() differ from the existing table's partition keys.

Common situations: Attempting ALTER TABLE to add/drop partition columns; regenerating a CatalogTable with a different PARTITIONED BY clause and passing it to alterTable; migration tooling that rewrites partition specs.

Related errors

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

Appendix: source

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