apache/iceberg · error · UnsupportedOperationException

Registering views is not supported

Error message

Registering views is not supported

What it means

ViewCatalog is an interface that adds view management to a catalog; registerView is a default method that deliberately throws UnsupportedOperationException because not every catalog implementation supports registering (importing) an existing view from a metadata file location. Implementations like HiveCatalog or JdbcCatalog may not override it, so calling it on such a catalog fails at runtime.

Source

Thrown at api/src/main/java/org/apache/iceberg/catalog/ViewCatalog.java:133

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

  /**
   * Register a view with the catalog if it does not exist.
   *
   * @param identifier a view identifier
   * @param metadataFileLocation the location of a metadata file
   * @return a View instance
   * @throws AlreadyExistsException if a table/view with the same identifier already exists in the
   *     catalog.
   */
  default View registerView(TableIdentifier identifier, String metadataFileLocation) {
    throw new UnsupportedOperationException("Registering views is not supported");
  }

  /**
   * Initialize a view catalog given a custom name and a map of catalog properties.
   *
   * <p>A custom view catalog implementation must have a no-arg constructor. A compute engine like
   * Spark or Flink will first initialize the catalog without any arguments, and then call this
   * method to complete catalog initialization with properties passed into the engine.
   *
   * @param name a custom name for the catalog
   * @param properties catalog properties
   */
  default void initialize(String name, Map<String, String> properties) {}
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Use a catalog implementation that overrides registerView (e.g., RESTCatalog with view support, NessieCatalog) instead of the default-throwing implementation.
  2. If the catalog supports creating views, recreate the view with createView/replaceView using its SQL or view definition instead of registering its metadata file.
  3. Before calling, feature-detect: try registerView and fall back to creation, or check the implementation class/documentation for view registration support.
  4. Add an override of registerView to your custom catalog implementation.
  5. Wrap the call in try-catch for UnsupportedOperationException and surface a clear 'view registration not supported by this catalog' message.

Example fix

// before
View view = catalog.registerView(ident, "s3://bucket/warehouse/db/view/metadata/00001-abc.metadata.json");
// after
View view;
try {
  view = catalog.registerView(ident, metadataLocation);
} catch (UnsupportedOperationException e) {
  view = catalog.buildView(ident)
      .withQueryCatalog("spark_catalog")
      .withQuery("spark", "SELECT * FROM db.tbl")
      .withSchema(schema)
      .create();
}
Defensive patterns

Strategy: type-guard

When it happens

Trigger: Calling catalog.registerView(identifier, metadataFileLocation) on a ViewCatalog implementation that does not override registerView (e.g., a catalog that supports views via create/replace but not metadata-file registration).

Common situations: Migrating views between catalogs by pointing at an existing metadata JSON file; tooling that assumes all view catalogs support view registration like table registration; using a custom or older catalog implementation that predates registerView 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

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