apache/iceberg · error · UnsupportedOperationException

Registering tables with overwrite is not supported

Error message

Registering tables with overwrite is not supported

What it means

Catalog.registerTable(identifier, metadataFileLocation, overwrite) throws UnsupportedOperationException when overwrite=true, unless the catalog implementation overrides it. Only the non-overwrite path is delegated to the two-argument registerTable default. The default method exists so catalogs can opt in to overwrite registration; most do not.

Source

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

  }

  /**
   * 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);
    }

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

  /**
   * Instantiate a builder to either create a table or start a create/replace transaction.
   *
   * @param identifier a table identifier
   * @param schema a schema
   * @return the builder to create a table or start a create/replace transaction
   */
  default TableBuilder buildTable(TableIdentifier identifier, Schema schema) {
    throw new UnsupportedOperationException(
        this.getClass().getName() + " does not implement buildTable");
  }

  /**
   * Initialize a catalog given a custom name and a map of catalog properties.
   *
   * <p>A custom Catalog implementation must have a no-arg constructor. A compute engine like Spark

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Call the two-argument registerTable(identifier, metadataFileLocation) instead, after dropping the existing table if replacement is intended
2. Upgrade to a catalog implementation that overrides the overwrite variant
3. Implement the three-argument registerTable in the custom catalog
4. If the table already exists, drop it first then re-register without overwrite

Example fix

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

if (overwrite && !catalogOverwriteSupported) {
  // fall back to drop + register
}

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

When it happens

Trigger: Calling the three-argument registerTable with overwrite=true on a Catalog that only overrides (or does not implement) the two-argument version.

Common situations: Re-registering a table over an existing entry during repair/migration scripts; force-swapping a table's metadata pointer after a botched operation; using a generic catalog reference whose backend doesn't allow overwrite.

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 is not supported
• this.getClass().getName() + " does not implement buildTable"
• Registering tables with overwrite is not supported
• Can't retrieve values from an empty struct
• Can't modify an empty struct

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