{"record":{"id":"5034b039ba9a4567","repo":"apache/iceberg","slug":"altering-schema-is-not-supported-in-the-old-altert-5034b0","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.1/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.1/flink/src/main/java/org/apache/iceberg/flink/FlinkCatalog.java#L460-L496","documentation":"The legacy alterTable(CatalogTable) API cannot express schema changes, so validateTableSchemaAndPartition rejects any call where the new table's unresolved schema differs from the existing table's. To change schema, callers must use the alterTable overload that accepts a list of TableChange objects.","triggerScenarios":"Calling the old alterTable(objectPath, newCatalogTable, ignoreIfNotExists) with a CatalogTable whose columns/types differ from the current table schema.","commonSituations":"Frameworks that materialize full table definitions and call the deprecated alterTable; users upgrading code to Flink 1.24+ style where schema changes moved to TableChange-based API.","solutions":["Switch to the TableChange-based alterTable(objectPath, SchemaChange/TableChange list, ignoreIfNotExists) API","Ensure the replacement CatalogTable has an identical unresolved schema when using the old API","Reframe the operation as drop-and-recreate if a full schema rewrite is truly needed (data loss risk)"],"exampleFix":"// before\ncatalog.alterTable(path, tableWithNewColumns, false);\n// after\ncatalog.alterTable(path, Arrays.asList(TableChange.addColumn(\"ts\", DataTypes.TIMESTAMP(3))), false);","handlingStrategy":"validation","validationCode":"if (!Objects.equals(existing.getUnresolvedSchema(), newTable.getUnresolvedSchema())) {\n  throw new IllegalStateException(\"Use the TableChange-based alterTable API for schema changes\");\n}","typeGuard":"null","tryCatchPattern":"try { catalog.alterTable(path, newTable, false); } catch (UnsupportedOperationException e) { /* switch to TableChange-based alter */ }","preventionTips":["Prefer the TableChange-based alterTable overload for all evolution","Compare unresolved schemas before calling the legacy alterTable","Never use the legacy API to push full table redefinitions"],"tags":["flink","iceberg-catalog","schema-evolution","deprecated-api"],"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-14T16:17:12.679Z"}