apache/iceberg · error · UnsupportedOperationException

does not support renaming tables

Error message

${CLASS_NAME} does not support renaming tables

What it means

Renaming a table would invalidate the staged-rewrite contract of SparkRewriteTableCatalog, so renameTable unconditionally throws UnsupportedOperationException with the class name. This catalog exists solely to stage create/replace during rewrite procedures.

Solutions

  1. Execute the rename against a full catalog implementation such as SparkCatalog backed by Hive/REST/Hadoop
  2. Drop and recreate the table with the new name using a full catalog if rename is unavoidable elsewhere
  3. Restrict the rewrite catalog registration to rewrite procedure sessions only

Example fix

// before
spark.sql.catalog.ice = org.apache.iceberg.spark.SparkRewriteTableCatalog
// after
spark.sql.catalog.ice = org.apache.iceberg.spark.SparkCatalog
Defensive patterns

Strategy: try-catch

Validate before calling

if (catalog instanceof SparkRewriteTableCatalog) {
  throw new IllegalStateException("renameTable not supported here; use the production catalog");
}

Type guard

boolean supportsRename(Catalog c) { return !(c instanceof SparkRewriteTableCatalog); }

Try / catch

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

Prevention

When it happens

Trigger: Calling renameTable(oldIdent, newIdent) on this catalog, or running ALTER TABLE ... RENAME TO where Spark routes the command to the rewrite catalog implementation.

Common situations: Session catalog configured as SparkRewriteTableCatalog; migration scripts renaming tables across catalogs; frameworks performing generic DDL against every registered catalog.

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/265c46887e0ab258. Report an issue: GitHub.

Appendix: source

Thrown at spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/SparkRewriteTableCatalog.java:100

  @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 void validateNoNamespace(Identifier ident) {
    Preconditions.checkArgument(
        ident.namespace().length == 0,
        "%s does not support namespaces, but got: %s",
        CLASS_NAME,
        String.join(".", ident.namespace()));

View on GitHub (pinned to 86d9c8fc54)