apache/iceberg · error · RuntimeException

Failed to rename to

Error message

Failed to rename ${from} to ${to}

What it means

A generic RuntimeException wrapping an InvalidOperationException from the Hive Metastore during rename when the exception message does NOT indicate an existing destination. It means the metastore refused the operation for another reason (e.g. invalid operation on the object type), and Iceberg has no more specific mapping. The original exception is attached as the cause.

Solutions

  1. Inspect the cause (e.getCause()) message to learn the actual metastore rejection reason.
  2. If the real cause is a name collision (older HMS error wording), drop/rename the destination first or upgrade to a version with better mapping.
  3. Check Hive Metastore version compatibility and metastore event/authorization configs that may block renames.

Example fix

// before
catalog.renameTable(from, to);
// after
try {
  catalog.renameTable(from, to);
} catch (RuntimeException e) {
  LOG.error("Rename rejected by metastore", e.getCause());
  throw e;
}
Defensive patterns

Strategy: try-catch

Try / catch

try { catalog.renameTable(from, to); } catch (RuntimeException e) { LOG.error("Metastore rejected rename: {}", e.getCause() != null ? e.getCause().getMessage() : e.getMessage(), e); throw e; }

Prevention

When it happens

Trigger: renameTable/renameView where the metastore throws InvalidOperationException with a message other than 'new table <to> already exists', e.g. metastore-side restrictions on the operation.

Common situations: Older Hive Metastore versions with different error text (the string match on 'already exists' misses it, downgrading an AlreadyExists case to this generic error); metastore configuration forbidding renames; renaming objects the metastore treats specially.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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

Appendix: source

Thrown at hive-metastore/src/main/java/org/apache/iceberg/hive/HiveCatalog.java:445

            return null;
          });

      LOG.info("Renamed {} from {}, to {}", contentType.value(), from, to);

    } catch (NoSuchObjectException e) {
      switch (contentType) {
        case TABLE:
          throw new NoSuchTableException("Cannot rename %s to %s. Table does not exist", from, to);
        case VIEW:
          throw new NoSuchViewException("Cannot rename %s to %s. View does not exist", from, to);
      }

    } catch (InvalidOperationException e) {
      if (e.getMessage() != null
          && e.getMessage().contains(String.format("new table %s already exists", to))) {
        throw new AlreadyExistsException("Table already exists: %s", to);
      } else {
        throw new RuntimeException("Failed to rename " + from + " to " + to, e);
      }

    } catch (TException e) {
      throw new RuntimeException("Failed to rename " + from + " to " + to, e);

    } catch (InterruptedException e) {
      Thread.currentThread().interrupt();
      throw new RuntimeException("Interrupted in call to rename", e);
    }
  }

  private void validateTableIsIcebergTableOrView(
      HiveOperationsBase.ContentType contentType, Table table, String fullName) {
    switch (contentType) {
      case TABLE:
        HiveOperationsBase.validateTableIsIceberg(table, fullName);
        break;
      case VIEW:

View on GitHub (pinned to 86d9c8fc54)