apache/iceberg · error · UnsupportedOperationException

Unsupported table change: ModifyWatermark.

Error message

Unsupported table change: ModifyWatermark.

What it means

Guard in FlinkAlterTableUtil.applySchemaChanges: an ALTER TABLE change of type ModifyWatermark was received. Watermark specs are not part of Iceberg table schemas, so the change cannot be translated into an UpdateSchema operation and is rejected outright.

Source

Thrown at flink/v1.20/flink/src/main/java/org/apache/iceberg/flink/util/FlinkAlterTableUtil.java:137

   *
   * @param pendingUpdate an uncommitted UpdateSchema operation to configure
   * @param schemaChanges a list of Flink table changes
   */
  public static void applySchemaChanges(
      UpdateSchema pendingUpdate, List<TableChange> schemaChanges) {
    for (TableChange change : schemaChanges) {
      if (change instanceof TableChange.AddColumn) {
        applyAddColumn(pendingUpdate, (TableChange.AddColumn) change);
      } else if (change instanceof TableChange.ModifyColumn) {
        TableChange.ModifyColumn modifyColumn = (TableChange.ModifyColumn) change;
        applyModifyColumn(pendingUpdate, modifyColumn);
      } else if (change instanceof TableChange.DropColumn) {
        TableChange.DropColumn dropColumn = (TableChange.DropColumn) change;
        pendingUpdate.deleteColumn(dropColumn.getColumnName());
      } else if (change instanceof TableChange.AddWatermark) {
        throw new UnsupportedOperationException("Unsupported table change: AddWatermark.");
      } else if (change instanceof TableChange.ModifyWatermark) {
        throw new UnsupportedOperationException("Unsupported table change: ModifyWatermark.");
      } else if (change instanceof TableChange.DropWatermark) {
        throw new UnsupportedOperationException("Unsupported table change: DropWatermark.");
      } else if (change instanceof TableChange.AddUniqueConstraint) {
        TableChange.AddUniqueConstraint addPk = (TableChange.AddUniqueConstraint) change;
        applyUniqueConstraint(pendingUpdate, addPk.getConstraint());
      } else if (change instanceof TableChange.ModifyUniqueConstraint) {
        TableChange.ModifyUniqueConstraint modifyPk = (TableChange.ModifyUniqueConstraint) change;
        applyUniqueConstraint(pendingUpdate, modifyPk.getNewConstraint());
      } else if (change instanceof TableChange.DropConstraint) {
        throw new UnsupportedOperationException("Unsupported table change: DropConstraint.");
      } else {
        throw new UnsupportedOperationException("Cannot apply unknown table change: " + change);
      }
    }
  }

  private static void applyAddColumn(UpdateSchema pendingUpdate, TableChange.AddColumn addColumn) {
    Column flinkColumn = addColumn.getColumn();

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Remove the MODIFY WATERMARK clause
2. Handle watermark changes in the Flink job's WatermarkStrategy, not the catalog table
3. Split the ALTER statement so only supported changes are applied

if (changes.stream().anyMatch(c -> c instanceof TableChange.ModifyWatermark)) {
  throw new IllegalArgumentException("Watermark changes are unsupported on Iceberg tables");
}

try {
  FlinkAlterTableUtil.applySchemaChanges(table, changes);
} catch (UnsupportedOperationException e) {
  // handle watermark-related failure separately
}

When it happens

Trigger: Running `ALTER TABLE ... MODIFY WATERMARK` (or ALTER ... ADD/MODIFY watermark after drop) against a table backed by the Iceberg Flink catalog.

Common situations: Adjusting watermark delay on a table previously defined with a Flink-specific watermark; migrating table definitions between Flink catalogs.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Unsupported table change: AddWatermark.
• Unsupported table change: DropWatermark.
• Creating table with watermark specs is not supported yet.
• Unsupported table change: AddWatermark.
• Unsupported table change: ModifyWatermark.

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