apache/iceberg · error · UnsupportedOperationException

Altering schema is not supported in the old alterTable API…

Error message

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.

What it means

An UnsupportedOperationException from validateTableSchemaAndPartition indicating the deprecated (old) alterTable API was called with a new CatalogTable whose unresolved schema differs from the current one. Schema changes must go through the alterTable API that accepts a list of TableChange objects.

Solutions

  1. Use the alterTable(ObjectPath, List<TableChange>) API instead, e.g. SchemaChange.addColumn/removeColumn/renameColumn/ updateColumn type.
  2. Upgrade the integration (or Flink version) so schema evolution uses the TableChange-based path.
  3. If only properties changed, ensure the new CatalogTable's schema is identical to the old one so this validation passes.

Example fix

// before
flinkCatalog.alterTable(path, newTableWithExtraColumn, false);
// after
flinkCatalog.alterTable(path, Collections.singletonList(SchemaChange.addColumn("c", Types.IntegerType.get())));
Defensive patterns

Strategy: validation

Validate before calling

if (!Objects.equals(oldTable.getUnresolvedSchema(), newTable.getUnresolvedSchema())) {
  // use alterTable(path, List<TableChange>) instead
}

Try / catch

try {
  flinkCatalog.alterTable(path, newTable, false);
} catch (UnsupportedOperationException e) {
  // fall back to alterTable(path, changes)
}

Prevention

When it happens

Trigger: Calling the legacy alterTable(ObjectPath, CatalogBaseTable, boolean) with a replacement CatalogTable that adds, drops, renames, or retypes columns compared to the existing table.

Common situations: Using Flink versions/tooling that still invokes the old alterTable signature; ALTER TABLE ADD/RENAME COLUMN statements routed through a code path using the legacy API; frameworks that rebuild the whole CatalogTable and pass it to the old API.

Understand the failure class

Background: "is deprecated and will be removed" — deprecation warnings for old API names, keywords, and options, and how to migrate before the removal release — this error's family across 29 libraries.

Related errors

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

Appendix: source

Thrown at flink/v2.3/flink/src/main/java/org/apache/iceberg/flink/FlinkCatalog.java:478

    try {
      icebergCatalog.createTable(
          toIdentifier(tablePath), icebergSchema, spec, location, properties.build());
    } catch (AlreadyExistsException e) {
      if (!ignoreIfExists) {
        throw new TableAlreadyExistException(getName(), tablePath, e);
      }
    }
  }

  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.

View on GitHub (pinned to 86d9c8fc54)