apache/iceberg · error · java.lang.UnsupportedOperationException

Cannot specify the 'sort-order' because it's a reserved tabl

Error message

Cannot specify the 'sort-order' because it's a reserved table property. Please use the command 'ALTER TABLE ... WRITE ORDERED BY' to specify write sort-orders.

What it means

Iceberg reserves the 'sort-order' table property for its internal sort-order metadata, so it cannot be set as a plain property via ALTER TABLE ... SET TBLPROPERTIES. SparkCatalog.alterTable rejects it with this UnsupportedOperationException and points to the dedicated syntax instead.

Source

Thrown at spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java:341

  @Override
  public Table alterTable(Identifier ident, TableChange... changes) throws NoSuchTableException {
    SetProperty setLocation = null;
    SetProperty setSnapshotId = null;
    SetProperty pickSnapshotId = null;
    List<TableChange> propertyChanges = Lists.newArrayList();
    List<TableChange> schemaChanges = Lists.newArrayList();

    for (TableChange change : changes) {
      if (change instanceof SetProperty) {
        SetProperty set = (SetProperty) change;
        if (TableCatalog.PROP_LOCATION.equalsIgnoreCase(set.property())) {
          setLocation = set;
        } else if ("current-snapshot-id".equalsIgnoreCase(set.property())) {
          setSnapshotId = set;
        } else if ("cherry-pick-snapshot-id".equalsIgnoreCase(set.property())) {
          pickSnapshotId = set;
        } else if ("sort-order".equalsIgnoreCase(set.property())) {
          throw new UnsupportedOperationException(
              "Cannot specify the 'sort-order' because it's a reserved table "
                  + "property. Please use the command 'ALTER TABLE ... WRITE ORDERED BY' to specify write sort-orders.");
        } else if ("identifier-fields".equalsIgnoreCase(set.property())) {
          throw new UnsupportedOperationException(
              "Cannot specify the 'identifier-fields' because it's a reserved table property. "
                  + "Please use the command 'ALTER TABLE ... SET IDENTIFIER FIELDS' to specify identifier fields.");
        } else {
          propertyChanges.add(set);
        }
      } else if (change instanceof RemoveProperty) {
        propertyChanges.add(change);
      } else if (change instanceof ColumnChange) {
        schemaChanges.add(change);
      } else {
        throw new UnsupportedOperationException("Cannot apply unknown table change: " + change);
      }
    }

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Use ALTER TABLE ... WRITE ORDERED BY col1, col2 [ASC|DESC] to set write sort order.
2. Remove 'sort-order' from SET TBLPROPERTIES and apply it via the write distribution/order clauses.
3. Use DataFrameWriterV2 with Spark 3.4+ ordered writes where applicable.
4. Inspect existing sort order with DESCRIBE TABLE / the sort-order metadata instead of the property.

Example fix

// before
ALTER TABLE db.events SET TBLPROPERTIES ('sort-order'='id ASC')
// after
ALTER TABLE db.events WRITE ORDERED BY id ASC

Set<String> reserved = Set.of("sort-order", "identifier-fields"); props.keySet().removeAll(reserved.stream().map(k -> k).filter(reserved::contains).collect(java.util.stream.Collectors.toSet()));

null

try { spark.sql(alterSql); } catch (UnsupportedOperationException e) { /* route to WRITE ORDERED BY */ }

When it happens

Trigger: ALTER TABLE ... SET TBLPROPERTIES ('sort-order'='...') on an Iceberg table; Spark sends the change to SparkCatalog.alterTable, which matches the reserved key case-insensitively at line 341 and throws.

Common situations: Migrating SQL that set sort order via properties in other engines; copying DDL from older Iceberg versions or non-Iceberg tables; LLM/templates generating SET TBLPROPERTIES for sort order.

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

• Cannot specify the 'identifier-fields' because it's a reserv
• Cannot specify the 'sort-order' because it's a reserved tabl
• Cannot specify the 'identifier-fields' because it's a reserv
• Cannot specify the 'sort-order' because it's a reserved tabl
• Cannot specify the 'sort-order' because it's a reserved tabl

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