{"record":{"id":"63f7561d02b0ab9d","repo":"apache/iceberg","slug":"cannot-update-the-sort-order-of-a-s-table","errorCode":null,"errorMessage":"Cannot update the sort order of a %s table","messagePattern":"Cannot update the sort order of a (.+?) table","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/BaseReadOnlyTable.java","lineNumber":49,"sourceCode":"    throw new UnsupportedOperationException(\n        \"Cannot update the schema of a \" + descriptor + \" table\");\n  }\n\n  @Override\n  public UpdatePartitionSpec updateSpec() {\n    throw new UnsupportedOperationException(\n        \"Cannot update the partition spec of a \" + descriptor + \" table\");\n  }\n\n  @Override\n  public UpdateProperties updateProperties() {\n    throw new UnsupportedOperationException(\n        \"Cannot update the properties of a \" + descriptor + \" table\");\n  }\n\n  @Override\n  public ReplaceSortOrder replaceSortOrder() {\n    throw new UnsupportedOperationException(\n        \"Cannot update the sort order of a \" + descriptor + \" table\");\n  }\n\n  @Override\n  public UpdateLocation updateLocation() {\n    throw new UnsupportedOperationException(\n        \"Cannot update the location of a \" + descriptor + \" table\");\n  }\n\n  @Override\n  public AppendFiles newAppend() {\n    throw new UnsupportedOperationException(\"Cannot append to a \" + descriptor + \" table\");\n  }\n\n  @Override\n  public RewriteFiles newRewrite() {\n    throw new UnsupportedOperationException(\"Cannot rewrite in a \" + descriptor + \" table\");\n  }","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/BaseReadOnlyTable.java#L31-L67","documentation":"Iceberg throws this UnsupportedOperationException when replaceSortOrder() is called on a read-only table. Changing the sort order is a metadata write, which BaseReadOnlyTable subclasses (e.g. metadata tables) never allow. The descriptor identifies the read-only table kind.","triggerScenarios":"Calling table.replaceSortOrder().asc(...).commit() on an instance extending BaseReadOnlyTable, such as a metadata table reference.","commonSituations":"Sort-order optimization routines applied generically to all Table handles, accidentally including metadata tables like table.snapshots().","solutions":["Run sort-order replacement on the writable data table from catalog.loadTable(identifier).","Skip sort-order updates for read-only/metadata table instances.","Use table.sortOrder() if the sort order only needs to be inspected."],"exampleFix":"// before\ntable.snapshots().replaceSortOrder().asc(\"id\").commit();\n\n// after\nTable dataTable = catalog.loadTable(TableIdentifier.of(\"db\", \"tbl\"));\ndataTable.replaceSortOrder().asc(\"id\").commit();","handlingStrategy":"try-catch","validationCode":"if (!canWrite(table)) { throw new IllegalArgumentException(\"Read-only table: \" + table.name()); } // canWrite checks the table was loaded from a catalog and is not a metadata table","typeGuard":"boolean canReplaceSortOrder = !(table instanceof BaseReadOnlyTable); // practical proxy: table loaded via catalog.loadTable","tryCatchPattern":"try {\n  table.replaceSortOrder().asc(\"id\").commit();\n} catch (UnsupportedOperationException e) {\n  log.error(\"Sort order is immutable on read-only table {}\", table.name(), e);\n}","preventionTips":["Run sort-order jobs only on catalog-loaded data tables.","Exclude metadata tables from optimization job table lists.","Read current order with table.sortOrder() instead of opening a replacement."],"tags":["unsupported-operation","sort-order","read-only-table"],"backgroundTag":"unsupported-operation","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"}