apache/iceberg · error · UnsupportedOperationException

Replacing a view is not supported by catalog: catalogName

Error message

Replacing a view is not supported by catalog: catalogName

What it means

SparkSessionCatalog delegates view operations to an underlying view catalog when one is configured; otherwise it only handles tables. This UnsupportedOperationException is thrown from replaceView when the wrapped catalog neither implements ViewCatalog nor is configured as a session view catalog, so replacing (CREATE OR REPLACE VIEW) a view cannot be performed.

Source

Thrown at spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/SparkSessionCatalog.java:525

      String[] columnAliases,
      String[] columnComments,
      Map<String, String> properties)
      throws NoSuchNamespaceException, NoSuchViewException {
    if (asViewCatalog instanceof SupportsReplaceView) {
      return ((SupportsReplaceView) asViewCatalog)
          .replaceView(
              ident,
              sql,
              currentCatalog,
              currentNamespace,
              schema,
              queryColumnNames,
              columnAliases,
              columnComments,
              properties);
    }

    throw new UnsupportedOperationException(
        "Replacing a view is not supported by catalog: " + catalogName);
  }

  @Override
  public View alterView(Identifier ident, ViewChange... changes)
      throws NoSuchViewException, IllegalArgumentException {
    if (null != asViewCatalog && asViewCatalog.viewExists(ident)) {
      return asViewCatalog.alterView(ident, changes);
    } else if (isViewCatalog()) {
      return getSessionCatalog().alterView(ident, changes);
    }

    throw new UnsupportedOperationException(
        "Altering a view is not supported by catalog: " + catalogName);
  }

  @Override
  public boolean dropView(Identifier ident) {

View on GitHub (pinned to 86d9c8fc54)

Solutions

Configure the catalog so its underlying implementation supports views (a catalog implementing org.apache.iceberg.view.ViewCatalog), e.g. use a REST/Hive/JDBC catalog with view support.
Drop the existing view and re-create it instead of replacing: DROP VIEW ident; CREATE VIEW ident AS ...
If the delegate catalog does support views, ensure the view actually exists there (viewExists(ident) path) so the delegation branch is taken.
Manage views in a different catalog that supports replace, or use engine-native (non-Iceberg) views for this metadata location.

Example fix

// before
spark.sql("CREATE OR REPLACE VIEW my_view AS SELECT * FROM t") // throws UnsupportedOperationException
// after
spark.sql("DROP VIEW IF EXISTS my_view")
spark.sql("CREATE VIEW my_view AS SELECT * FROM t")

Defensive patterns

Strategy: try-catch

Validate before calling

// before replace
ViewCatalog vc = ((SparkCatalog) sparkCatalog).asViewCatalog();
if (vc == null) { /* catalog does not support views: use drop+create */ }

Type guard

boolean supportsViewReplace = sparkCatalog instanceof SparkCatalog
    && ((SparkCatalog) sparkCatalog).asViewCatalog() != null;

Try / catch

try {
  catalog.replaceView(ident, schema, spec, location, props);
} catch (UnsupportedOperationException e) {
  if (e.getMessage().contains("Replacing a view")) { catalog.dropView(ident); catalog.createView(ident, ...); }
  else throw e;
}

Prevention

Choose a catalog implementation that implements ViewCatalog before defining views in it.
Check asViewCatalog()/ViewCatalog support at session setup time, not at first write.
Avoid CREATE OR REPLACE VIEW in migrations targeting view-less catalogs.

When it happens

Trigger: Calling SparkCatalog/SparkSessionCatalog.replaceView(ident, ...) (e.g. via CREATE OR REPLACE VIEW SQL) when asViewCatalog is null, the ident does not exist as a view in a delegate view catalog, and isViewCatalog() is false for catalogName.

Common situations: Using CREATE OR REPLACE VIEW against a catalog (e.g. HadoopCatalog, Hive Metastore without view support in the configured delegate, or a third-party catalog) that does not implement the Iceberg ViewCatalog interface; running against a session catalog whose underlying implementation only supports tables.

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/b3e17ce338cdb62b. Report an issue: GitHub.