apache/iceberg · error · UnsupportedOperationException

does not support renaming tables

Error message

 does not support renaming tables

What it means

This UnsupportedOperationException is a deliberate guard in SparkCachedTableCatalog.renameTable: the catalog maintains a cache keyed by table identifier and cannot move or re-key an entry, nor can it rename the table in the catalog that actually owns it. ALTER TABLE ... RENAME TO statements resolved through this catalog raise this sentinel unconditionally, with no side effects on the cached or underlying table.

Solutions

  1. Rename the table in the owning Iceberg catalog
  2. Re-cache under the new identifier after renaming in the real catalog
  3. Qualify the RENAME with the real catalog name
Defensive patterns

Strategy: validation

Validate before calling

if (catalog instanceof SparkCachedTableCatalog) {
  throw new IllegalArgumentException("RENAME not supported on cached catalog; use owning catalog");
}

Try / catch

try { catalog.renameTable(oldIdent, newIdent); } catch (UnsupportedOperationException e) { realCatalog.renameTable(oldIdent, newIdent); }

Prevention

When it happens

Trigger: Running ALTER TABLE ... RENAME TO or Catalog#renameTable on identifiers belonging to the cached-table catalog.

Common situations: Migration/refactoring scripts renaming tables routed to the wrong catalog; Spark session catalog misconfiguration.

Related errors

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

Appendix: source

Thrown at spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/SparkCachedTableCatalog.java:118

  @Override
  public SparkTable alterTable(Identifier ident, TableChange... changes) {
    throw new UnsupportedOperationException(CLASS_NAME + " does not support altering tables");
  }

  @Override
  public boolean dropTable(Identifier ident) {
    throw new UnsupportedOperationException(CLASS_NAME + " does not support dropping tables");
  }

  @Override
  public boolean purgeTable(Identifier ident) throws UnsupportedOperationException {
    throw new UnsupportedOperationException(CLASS_NAME + " does not support purging tables");
  }

  @Override
  public void renameTable(Identifier oldIdent, Identifier newIdent) {
    throw new UnsupportedOperationException(CLASS_NAME + " does not support renaming tables");
  }

  @Override
  public void initialize(String catalogName, CaseInsensitiveStringMap options) {
    this.name = catalogName;
  }

  @Override
  public String name() {
    return name;
  }

  private SparkTable load(Identifier ident) throws NoSuchTableException {
    Preconditions.checkArgument(
        ident.namespace().length == 0, CLASS_NAME + " does not support namespaces");

    Pair<String, List<String>> parsedIdent = parseIdent(ident);
    String key = parsedIdent.first();

View on GitHub (pinned to 86d9c8fc54)