apache/iceberg · error · UnsupportedOperationException

Cannot update the properties of a %s table

Error message

Cannot update the properties of a %s table

What it means

Iceberg throws this UnsupportedOperationException when updateProperties() is called on a read-only table. Setting table properties writes table metadata, which BaseReadOnlyTable subclasses deliberately reject. The descriptor names the read-only table kind in the message.

Source

Thrown at core/src/main/java/org/apache/iceberg/BaseReadOnlyTable.java:43

  BaseReadOnlyTable(String descriptor) {
    this.descriptor = descriptor;
  }

  @Override
  public UpdateSchema updateSchema() {
    throw new UnsupportedOperationException(
        "Cannot update the schema of a " + descriptor + " table");
  }

  @Override
  public UpdatePartitionSpec updateSpec() {
    throw new UnsupportedOperationException(
        "Cannot update the partition spec of a " + descriptor + " table");
  }

  @Override
  public UpdateProperties updateProperties() {
    throw new UnsupportedOperationException(
        "Cannot update the properties of a " + descriptor + " table");
  }

  @Override
  public ReplaceSortOrder replaceSortOrder() {
    throw new UnsupportedOperationException(
        "Cannot update the sort order of a " + descriptor + " table");
  }

  @Override
  public UpdateLocation updateLocation() {
    throw new UnsupportedOperationException(
        "Cannot update the location of a " + descriptor + " table");
  }

  @Override
  public AppendFiles newAppend() {
    throw new UnsupportedOperationException("Cannot append to a " + descriptor + " table");

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Apply the property update on the writable data table loaded via catalog.loadTable(identifier).
2. Filter out metadata tables before running generic property-update code.
3. If properties only need to be read, use table.properties().

Example fix

// before
table.files().updateProperties().set("write.format.default", "parquet").commit();

// after
Table dataTable = catalog.loadTable(TableIdentifier.of("db", "tbl"));
dataTable.updateProperties().set("write.format.default", "parquet").commit();

if (table.name().contains(".")) {
  // metadata tables are named like "table.snapshots"; base tables are not dotted
  throw new IllegalArgumentException("Refusing to set properties on: " + table.name());
}

boolean isMetadataTable = table.name().lastIndexOf('.') > 0; // metadata tables carry dotted names

try {
  table.updateProperties().set(key, value).commit();
} catch (UnsupportedOperationException e) {
  log.error("Cannot set properties on read-only table {}", table.name(), e);
}

When it happens

Trigger: Calling table.updateProperties().set(...) on a metadata table (e.g. table.snapshots()) or any other BaseReadOnlyTable subclass instance.

Common situations: Configuration automation that applies property sets to any Table it finds, including metadata tables obtained from table.metadataTableReferences() or direct snapshots()/files() references.

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 update the schema of a %s table
• Cannot update the partition spec of a %s table
• Cannot update the sort order of a %s table
• Cannot update the location of a %s table
• Cannot append to a %s table

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