apache/iceberg · error · UnsupportedOperationException

Registering tables with overwrite is not supported

Error message

Registering tables with overwrite is not supported

What it means

SessionCatalog.registerTable(context, ident, metadataFileLocation, overwrite) throws UnsupportedOperationException when overwrite=true unless the session-scoped catalog overrides it. Like the plain Catalog interface, only the non-overwrite case falls back to the two-argument registerTable default. It indicates the SessionCatalog implementation does not support overwrite registration.

Source

Thrown at api/src/main/java/org/apache/iceberg/catalog/SessionCatalog.java:196

   *
   * @param context session context
   * @param ident a table identifier
   * @param metadataFileLocation the location of a metadata file
   * @param overwrite whether to overwrite an existing table registration
   * @return a Table instance
   * @throws AlreadyExistsException if {@code overwrite} is false and the table already exists in
   *     the catalog
   */
  default Table registerTable(
      SessionContext context,
      TableIdentifier ident,
      String metadataFileLocation,
      boolean overwrite) {
    if (!overwrite) {
      return registerTable(context, ident, metadataFileLocation);
    }

    throw new UnsupportedOperationException("Registering tables with overwrite is not supported");
  }

  /**
   * Check whether table exists.
   *
   * @param context session context
   * @param ident a table identifier
   * @return true if the table exists, false otherwise
   */
  default boolean tableExists(SessionContext context, TableIdentifier ident) {
    try {
      loadTable(context, ident);
      return true;
    } catch (NoSuchTableException e) {
      return false;
    }
  }

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Call the non-overload registerTable(context, ident, metadataFileLocation) after dropping any existing table
2. Upgrade to a SessionCatalog implementation that supports overwrite registration
3. Override the four-argument registerTable in the custom SessionCatalog
4. Restructure the workflow to avoid overwrite semantics (new identifier or drop-then-register)

Example fix

// before
sessionCatalog.registerTable(context, ident, metadataFileLocation, true);
// after
sessionCatalog.dropTable(context, ident);
sessionCatalog.registerTable(context, ident, metadataFileLocation);

if (overwrite) {
  // verify the SessionCatalog implementation supports overwrite registration first
}

try {
  sessionCatalog.registerTable(context, ident, metadataFileLocation, true);
} catch (UnsupportedOperationException e) {
  sessionCatalog.dropTable(context, ident);
  sessionCatalog.registerTable(context, ident, metadataFileLocation);
}

When it happens

Trigger: Calling registerTable with overwrite=true on a SessionCatalog implementation that has not overridden the four-argument method, typically reached through an ASGC/IsolatedViewEngine or wrapped session catalog path.

Common situations: Custom session catalogs (in-memory, test stubs, wrappers around catalogs lacking registration) used in multi-session engines; overwrite-style table re-registration in session-scoped engines; version drift where the wrapper predates the overwrite API.

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

• Registering tables with overwrite is not supported
• Can't retrieve values from an empty struct
• Can't modify an empty struct
• %s doesn't implement cleanupLevel
• %s doesn't implement cleanExpiredMetadata

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