{"record":{"id":"c5f44e83044ff743","repo":"apache/iceberg","slug":"altering-schema-is-not-supported-in-the-old-altert-c5f44e","errorCode":null,"errorMessage":"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.","messagePattern":"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\\.","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"flink/v2.3/flink/src/main/java/org/apache/iceberg/flink/FlinkCatalog.java","lineNumber":478,"sourceCode":"    try {\n      icebergCatalog.createTable(\n          toIdentifier(tablePath), icebergSchema, spec, location, properties.build());\n    } catch (AlreadyExistsException e) {\n      if (!ignoreIfExists) {\n        throw new TableAlreadyExistException(getName(), tablePath, e);\n      }\n    }\n  }\n\n  private boolean isReservedProperty(String prop) {\n    return FlinkCreateTableOptions.LOCATION_KEY.equalsIgnoreCase(prop)\n        || FlinkCreateTableOptions.CONNECTOR_PROPS_KEY.equalsIgnoreCase(prop)\n        || FlinkCreateTableOptions.SRC_CATALOG_PROPS_KEY.equalsIgnoreCase(prop);\n  }\n\n  private static void validateTableSchemaAndPartition(CatalogTable ct1, CatalogTable ct2) {\n    if (!Objects.equals(ct1.getUnresolvedSchema(), ct2.getUnresolvedSchema())) {\n      throw new UnsupportedOperationException(\n          \"Altering schema is not supported in the old alterTable API. \"\n              + \"To alter schema, use the other alterTable API and provide a list of TableChange's.\");\n    }\n\n    validateTablePartition(ct1, ct2);\n  }\n\n  private static void validateTablePartition(CatalogTable ct1, CatalogTable ct2) {\n    if (!ct1.getPartitionKeys().equals(ct2.getPartitionKeys())) {\n      throw new UnsupportedOperationException(\"Altering partition keys is not supported yet.\");\n    }\n  }\n\n  /**\n   * This alterTable API only supports altering table properties.\n   *\n   * <p>Support for adding/removing/renaming columns cannot be done by comparing CatalogTable\n   * instances, unless the Flink schema contains Iceberg column IDs.","sourceCodeStart":460,"sourceCodeEnd":496,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/flink/v2.3/flink/src/main/java/org/apache/iceberg/flink/FlinkCatalog.java#L460-L496","documentation":"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.","triggerScenarios":"Calling the legacy alterTable(ObjectPath, CatalogBaseTable, boolean) with a replacement CatalogTable that adds, drops, renames, or retypes columns compared to the existing table.","commonSituations":"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.","solutions":["Use the alterTable(ObjectPath, List<TableChange>) API instead, e.g. SchemaChange.addColumn/removeColumn/renameColumn/ updateColumn type.","Upgrade the integration (or Flink version) so schema evolution uses the TableChange-based path.","If only properties changed, ensure the new CatalogTable's schema is identical to the old one so this validation passes."],"exampleFix":"// before\nflinkCatalog.alterTable(path, newTableWithExtraColumn, false);\n// after\nflinkCatalog.alterTable(path, Collections.singletonList(SchemaChange.addColumn(\"c\", Types.IntegerType.get())));","handlingStrategy":"validation","validationCode":"if (!Objects.equals(oldTable.getUnresolvedSchema(), newTable.getUnresolvedSchema())) {\n  // use alterTable(path, List<TableChange>) instead\n}","typeGuard":null,"tryCatchPattern":"try {\n  flinkCatalog.alterTable(path, newTable, false);\n} catch (UnsupportedOperationException e) {\n  // fall back to alterTable(path, changes)\n}","preventionTips":["Always use the TableChange-based alterTable API for schema changes","Only pass the legacy API tables whose schema is unchanged","Keep your Flink/Iceberg integration version current"],"tags":["flink","schema-evolution","unsupported","api-misuse"],"backgroundTag":"deprecated-api-usage","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}