apache/iceberg · error · UnsupportedOperationException

Registering tables is not supported

Error message

Registering tables is not supported

What it means

Catalog.registerTable(TableIdentifier, String) is a default interface method that throws UnsupportedOperationException. Catalogs are not required to support registering an existing table from a metadata file location; those that do must override this method. Hitting this error means the concrete Catalog implementation in use does not implement table registration.

Source

Thrown at api/src/main/java/org/apache/iceberg/catalog/Catalog.java:363

   * <p>If the table is already loaded or cached, drop cached data. If the table does not exist or
   * is not cached, do nothing.
   *
   * @param identifier a table identifier
   */
  default void invalidateTable(TableIdentifier identifier) {}

  /**
   * Register a table with the catalog if it does not exist.
   *
   * <p>For overwrite support, see {@link #registerTable(TableIdentifier, String, boolean)}.
   *
   * @param identifier a table identifier
   * @param metadataFileLocation the location of a metadata file
   * @return a Table instance
   * @throws AlreadyExistsException if the table already exists in the catalog.
   */
  default Table registerTable(TableIdentifier identifier, String metadataFileLocation) {
    throw new UnsupportedOperationException("Registering tables is not supported");
  }

  /**
   * Register a table with the catalog.
   *
   * @param identifier 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(
      TableIdentifier identifier, String metadataFileLocation, boolean overwrite) {
    if (!overwrite) {
      return registerTable(identifier, metadataFileLocation);
    }

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Switch to a catalog implementation that supports registration (e.g. HiveCatalog, JDBC, Nessie, REST)
2. Drop the registerTable call and recreate the table via createTable with the same data instead
3. Override registerTable in the custom Catalog implementation
4. Check the concrete catalog class and its docs for registerTable support before calling

Example fix

// before
catalog.registerTable(TableIdentifier.of("db", "t"), "s3://bucket/db/t/metadata/00001-xyz.metadata.json");
// after
// Use a catalog that implements registration, e.g.:
Catalog catalog = CatalogUtil.loadCatalog("org.apache.iceberg.jdbc.JdbcCatalog", ...);
catalog.registerTable(TableIdentifier.of("db", "t"), metadataFileLocation);

// Check catalog capability before calling (reflectively or via docs)
boolean supportsRegister = !(catalog.getClass().getSimpleName().equals("HadoopCatalog"));

try {
  return catalog.registerTable(ident, metadataFileLocation);
} catch (UnsupportedOperationException e) {
  throw new IllegalStateException("Catalog " + catalog.getClass().getName() + " cannot register tables", e);
}

When it happens

Trigger: Calling catalog.registerTable(identifier, metadataFileLocation) on a Catalog implementation (e.g. HadoopCatalog or custom in-memory/user catalog) that has not overridden the default method.

Common situations: Migrating tables between catalogs by pointing a new catalog at existing metadata.json files; disaster recovery re-registration scripts; using a generic Catalog reference where the concrete catalog lacks register 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

• Registering tables with overwrite is not supported
• this.getClass().getName() + " does not implement buildTable"
• Can't retrieve values from an empty struct
• Can't modify an empty struct
• %s doesn't implement cleanupLevel

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