apache/iceberg · error · UnsupportedOperationException

Cannot rename Hadoop tables

Error message

Cannot rename Hadoop tables

What it means

HadoopCatalog.renameTable is unconditionally unsupported: the Hadoop catalog stores tables as directories with no rename metadata support, so calling renameTable always throws UnsupportedOperationException. Applications must use a catalog that supports renames (e.g. Hive, JDBC, REST).

Source

Thrown at core/src/main/java/org/apache/iceberg/hadoop/HadoopCatalog.java:276

      if (lastMetadata == null) {
        LOG.debug("Not an iceberg table: {}", identifier);
        return false;
      } else {
        if (purge) {
          // Since the data files and the metadata files may store in different locations,
          // so it has to call dropTableData to force delete the data file.
          CatalogUtil.dropTableData(ops.io(), lastMetadata);
        }
        return fs.delete(tablePath, true /* recursive */);
      }
    } catch (IOException e) {
      throw new RuntimeIOException(e, "Failed to delete file: %s", tablePath);
    }
  }

  @Override
  public void renameTable(TableIdentifier from, TableIdentifier to) {
    throw new UnsupportedOperationException("Cannot rename Hadoop tables");
  }

  @Override
  public void createNamespace(Namespace namespace, Map<String, String> meta) {
    Preconditions.checkArgument(
        !namespace.isEmpty(), "Cannot create namespace with invalid name: %s", namespace);
    if (!meta.isEmpty()) {
      throw new UnsupportedOperationException(
          "Cannot create namespace " + namespace + ": metadata is not supported");
    }

    Path nsPath = new Path(warehouseLocation, SLASH.join(namespace.levels()));

    if (isNamespace(nsPath)) {
      throw new AlreadyExistsException("Namespace already exists: %s", namespace);
    }

    try {

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Do not call renameTable on HadoopCatalog; restructure code to avoid renames.
2. Achieve a rename manually: create the new table (e.g. via table copy or data migration) then drop the old one.
3. Switch to HiveCatalog, JdbcCatalog, or RESTCatalog if renames are a hard requirement.
4. Wrap the call in a check of catalog type and surface a clear 'unsupported' message to users.
5. Vote/use the Iceberg RenameTable developments — check your Iceberg version for HadoopCatalog rename support.

Example fix

// before
catalog.renameTable(from, to);

// after: guard against unsupported catalogs
if (catalog instanceof HadoopCatalog) {
  throw new UnsupportedOperationException("Use Hive/JDBC catalog for renames");
}
catalog.renameTable(from, to);

if (catalog instanceof HadoopCatalog) { throw new UnsupportedOperationException("renameTable unsupported on HadoopCatalog"); }

if (catalog instanceof HadoopCatalog) { /* use copy+drop or different catalog */ }

try { catalog.renameTable(from, to); } catch (UnsupportedOperationException e) { // fall back to create-new + migrate + drop }

When it happens

Trigger: Any call to catalog.renameTable(from, to) on a HadoopCatalog instance — there is no condition; every invocation throws.

Common situations: Code written against a HiveCatalog or JDBC catalog being reused with HadoopCatalog, generic 'rename table' admin tooling, or migration scripts moving environments to a filesystem warehouse.

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 create namespace " + namespace + ": metadata is not s
• Renaming a view is not supported by catalog: catalogName
• does not support renaming tables
• Renaming a view is not supported by catalog:
• Renaming a view is not supported by catalog: ${catalogName}

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