What causes "Table rename operation is unsupported." in apache/iceberg?

Drop the table and recreate it at the new identifier with the same schema/data location.

apache/iceberg · error · UnsupportedOperationException

Table rename operation is unsupported.

Error message

Table rename operation is unsupported.

What it means

Unconditional guard in BigQueryMetastoreCatalog.renameTable: the BigQuery API (at the time of writing, per the TODO) has no rename support, so every rename attempt is rejected up front. It is a permanent capability limitation of the catalog, independent of whether the source table exists.

Source

Thrown at bigquery/src/main/java/org/apache/iceberg/gcp/bigquery/BigQueryMetastoreCatalog.java:185

      TableOperations ops = newTableOps(identifier);
      TableMetadata lastMetadata = ops.current();

      client.delete(toTableReference(identifier));

      if (purge && lastMetadata != null) {
        CatalogUtil.dropTableData(ops.io(), lastMetadata);
      }
    } catch (NoSuchTableException e) {
      return false;
    }

    return true;
  }

  @Override
  public void renameTable(TableIdentifier from, TableIdentifier to) {
    // TODO: Enable once supported by BigQuery API.
    throw new UnsupportedOperationException("Table rename operation is unsupported.");
  }

  @Override
  public void createNamespace(Namespace namespace, Map<String, String> metadata) {
    Dataset builder = new Dataset();
    DatasetReference datasetReference = toDatasetReference(namespace);
    builder.setLocation(this.projectLocation);
    builder.setDatasetReference(datasetReference);
    builder.setExternalCatalogDatasetOptions(
        BigQueryMetastoreUtils.createExternalCatalogDatasetOptions(
            createDefaultStorageLocationUri(datasetReference.getDatasetId()), metadata));

    client.create(builder);
  }

  @Override
  public List<Namespace> listNamespaces() {
    try {

View on GitHub (pinned to 86d9c8fc54)

Solutions

Drop the table and recreate it at the new identifier with the same schema/data location.
Use a different catalog that supports renames if renames are essential to your workflow.
Restructure tooling/scripts to avoid rename operations when using the BigQuery catalog.

Defensive patterns

Strategy: try-catch

Validate before calling

if (catalog instanceof BigQueryMetastoreCatalog) { throw new UnsupportedOperationException("Rename is not supported by BigQueryMetastoreCatalog"); }

Try / catch

try { catalog.renameTable(from, to); } catch (UnsupportedOperationException e) { // fall back to drop+create or surface to user
}

Prevention

Feature-detect rename support before calling; the BigQuery catalog never supports it.
Replace rename workflows with drop-and-recreate.
Document catalog capability limitations for users running SQL engines.

When it happens

Trigger: Any call to catalog.renameTable(from, to) on BigQueryMetastoreCatalog, e.g. via SQL ALTER TABLE ... RENAME TO routed through this catalog.

Common situations: Running ALTER TABLE RENAME or engine-level rename APIs against a BigQuery-backed Iceberg catalog; migration scripts assuming rename support.

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/4ba70a40fb5b5535. Report an issue: GitHub.