apache/iceberg · error · java.lang.UnsupportedOperationException

Cannot specify the 'identifier-fields' because it's a reserv

Error message

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.

What it means

'identifier-fields' is a reserved Iceberg table property used to declare identifier fields, and it cannot be set via generic TBLPROPERTIES. alterTable rejects attempts with this UnsupportedOperationException and points to the dedicated ALTER TABLE ... SET IDENTIFIER FIELDS command.

Source

Thrown at spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java:297

    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);
      }
    }

    try {
      org.apache.iceberg.Table table = icebergCatalog.loadTable(buildIdentifier(ident));
      commitChanges(
          table, setLocation, setSnapshotId, pickSnapshotId, propertyChanges, schemaChanges);

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Use ALTER TABLE ... SET IDENTIFIER FIELDS col1, col2 to define identifier fields.
2. Remove the 'identifier-fields' key from the SET TBLPROPERTIES clause.
3. Inspect current identifier fields via DESCRIBE TABLE EXTENDED instead of rewriting the property.
4. Migrate automation to the dedicated identifier-fields DDL syntax.

Example fix

-- before
ALTER TABLE t SET TBLPROPERTIES ('identifier-fields'='id');
-- after
ALTER TABLE t SET IDENTIFIER FIELDS id;

-- Application-side precheck
if (props.containsKey("identifier-fields")) {
  throw new IllegalArgumentException(
      "Use ALTER TABLE ... SET IDENTIFIER FIELDS instead of the reserved property");
}

try {
  spark.sql(alterStatement);
} catch (UnsupportedOperationException e) {
  if (e.getMessage().contains("identifier-fields")) {
    // rewrite to ALTER TABLE ... SET IDENTIFIER FIELDS <cols>
  }
}

When it happens

Trigger: ALTER TABLE ... SET TBLPROPERTIES ('identifier-fields'='col') on an Iceberg table via SparkCatalog.alterTable.

Common situations: Users configuring upsert/key semantics by writing the property directly; scripts generated from documentation snippets that predate the SET IDENTIFIER FIELDS syntax; copying property-based setup from other engines.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Cannot specify the 'identifier-fields' because it's a reserv
• Cannot specify the 'identifier-fields' because it's a reserv
• Cannot specify the 'sort-order' because it's a reserved tabl
• Unsupported format in USING: ${provider}
• Cannot add column %s since setting default values in Spark i

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