apache/iceberg · error · UnsupportedOperationException

Cannot overwrite in a

Error message

Cannot overwrite in a %s table

What it means

Iceberg throws this UnsupportedOperationException when newOverwrite() is called on a read-only table. Overwriting files replaces data and commits a snapshot, a write that BaseReadOnlyTable subclasses never allow. The descriptor identifies the read-only table kind.

Solutions

1. Perform overwrites on the writable data table from catalog.loadTable(identifier).
2. Assert the Table is not a read-only/metadata table before starting overwrite work.
3. Use table.newDelete() on the data table if the intent was only removing files.

Example fix

// before
table.files().newOverwrite().overwriteByRowFilter(expr).commit();

// after
Table dataTable = catalog.loadTable(TableIdentifier.of("db", "tbl"));
dataTable.newOverwrite().overwriteByRowFilter(expr).commit();

if (isMetadataTableName(table.name())) { throw new IllegalArgumentException("Cannot overwrite files of metadata table " + table.name()); }

boolean canOverwrite = !(table instanceof BaseReadOnlyTable); // ensure handle came from Catalog.loadTable

try {
  table.newOverwrite().overwriteByRowFilter(expr).commit();
} catch (UnsupportedOperationException e) {
  log.error("Overwrite is not supported on read-only table {}", table.name(), e);
}

When it happens

Trigger: Calling table.newOverwrite().overwriteByRowFilter(...).commit() (or addFile/deleteFile variants) on a metadata table or any BaseReadOnlyTable subclass instance.

Common situations: Data-fix/backfill jobs that resolve Table objects loosely and end up with a metadata-table handle, then attempt overwrite corrections.

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 append to a table
• Cannot create transactions for a
• Cannot delete from a
• Cannot expire snapshots from a
• Cannot manage snapshots in a

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

Appendix: source

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

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

  @Override
  public RewriteFiles newRewrite() {
    throw new UnsupportedOperationException("Cannot rewrite in a " + descriptor + " table");
  }

  @Override
  public RewriteManifests rewriteManifests() {
    throw new UnsupportedOperationException(
        "Cannot rewrite manifests in a " + descriptor + " table");
  }

  @Override
  public OverwriteFiles newOverwrite() {
    throw new UnsupportedOperationException("Cannot overwrite in a " + descriptor + " table");
  }

  @Override
  public RowDelta newRowDelta() {
    throw new UnsupportedOperationException(
        "Cannot remove or replace rows in a " + descriptor + " table");
  }

  @Override
  public ReplacePartitions newReplacePartitions() {
    throw new UnsupportedOperationException(
        "Cannot replace partitions in a " + descriptor + " table");
  }

  @Override
  public DeleteFiles newDelete() {
    throw new UnsupportedOperationException("Cannot delete from a " + descriptor + " table");
  }

View on GitHub (pinned to 86d9c8fc54)