apache/iceberg · error · java.lang.UnsupportedOperationException

SparkCachedTableCatalog does not support renaming tables

Error message

SparkCachedTableCatalog does not support renaming tables

What it means

SparkCachedTableCatalog.renameTable() throws UnsupportedOperationException in all cases. Renaming is a metadata mutation on the owning catalog; the cached catalog is a read-only projection and cannot move or re-key table entries.

Source

Thrown at spark/v3.5/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)

Solutions

Perform the rename against the real catalog with fully qualified identifiers (ALTER TABLE spark_catalog.db.old RENAME TO ...).
Programmatically use the owning SupportsRename catalog's renameTable method.
If only a different cached alias is needed, load the table again under the new key instead of renaming.

Example fix

// before
cachedCatalog.renameTable(oldIdent, newIdent);

// after
spark.sql("ALTER TABLE spark_catalog.db.old_name RENAME TO spark_catalog.db.new_name");

Defensive patterns

Strategy: validation

Validate before calling

if (catalog instanceof SparkCachedTableCatalog) {
  throw new IllegalArgumentException("renameTable is not supported on SparkCachedTableCatalog; use the owning catalog");
}

Type guard

boolean canRename = !(catalog instanceof SparkCachedTableCatalog);

Try / catch

try {
  catalog.renameTable(oldIdent, newIdent);
} catch (UnsupportedOperationException e) {
  // rename via spark_catalog / owning catalog
}

Prevention

Perform renames with fully qualified identifiers in the owning catalog.
If only a different cache key is needed, re-load the table under the new key instead of renaming.
Keep cached-catalog usage confined to read/query paths.

When it happens

Trigger: Calling SparkCachedTableCatalog.renameTable(oldIdent, newIdent), or ALTER TABLE ... RENAME TO in Spark SQL when either identifier resolves to the cached catalog.

Common situations: Migration scripts renaming tables after a cached read; generic catalog-abstraction layers that issue rename uniformly; users expecting the cached alias to be renamable.

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

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