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

SparkCatalog throws this from replaceView when the underlying Iceberg catalog does not implement the ViewCatalog interface (asViewCatalog is null). The SQL REPLACE VIEW statement cannot be executed because view replacement is a catalog capability, and the configured catalog only supports tables. It signals a catalog capability gap, not a problem with the view itself.

Source

Thrown at spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java:688

        org.apache.iceberg.view.View view =
            asViewCatalog
                .buildView(buildIdentifier(ident))
                .withDefaultCatalog(currentCatalog)
                .withDefaultNamespace(Namespace.of(currentNamespace))
                .withQuery("spark", sql)
                .withSchema(icebergSchema)
                .withLocation(properties.get("location"))
                .withProperties(props)
                .createOrReplace();
        return new SparkView(catalogName, view);
      } catch (org.apache.iceberg.exceptions.NoSuchNamespaceException e) {
        throw new NoSuchNamespaceException(currentNamespace);
      } catch (org.apache.iceberg.exceptions.NoSuchViewException e) {
        throw new NoSuchViewException(ident);
      }
    }

    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) {
      try {
        org.apache.iceberg.view.View view = asViewCatalog.loadView(buildIdentifier(ident));
        UpdateViewProperties updateViewProperties = view.updateProperties();

        for (ViewChange change : changes) {
          if (change instanceof ViewChange.SetProperty) {
            ViewChange.SetProperty property = (ViewChange.SetProperty) change;
            verifyNonReservedPropertyIsSet(property.property());
            updateViewProperties.set(property.property(), property.value());
          } else if (change instanceof ViewChange.RemoveProperty) {
            ViewChange.RemoveProperty remove = (ViewChange.RemoveProperty) change;

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Use a catalog that implements org.apache.iceberg.catalog.ViewCatalog (REST catalog, HiveCatalog, JDBC catalog, Nessie) in spark.sql.catalog.<name>.
  2. Drop and recreate the view manually instead of REPLACE VIEW.
  3. If you control the catalog implementation, extend ViewCatalog and implement replaceView.

Example fix

// before
spark.conf.set("spark.sql.catalog.local", "org.apache.iceberg.spark.SparkCatalog")
spark.conf.set("spark.sql.catalog.local.catalog-impl", HADOOP_CATALOG)
// after
spark.conf.set("spark.sql.catalog.local.catalog-impl", "org.apache.iceberg.rest.RESTCatalog") // ViewCatalog-capable backend
Defensive patterns

Strategy: validation

Validate before calling

// before issuing REPLACE VIEW
if (!(catalogRef instanceof org.apache.iceberg.catalog.ViewCatalog)) {
  throw new IllegalStateException("Catalog does not support views; REPLACE VIEW unavailable");
}

Prevention

When it happens

Trigger: Executing 'CREATE OR REPLACE VIEW' or 'REPLACE VIEW' through Spark SQL when the session catalog (e.g. HadoopCatalog, JDBC without view support, or a REST catalog lacking view support) does not implement ViewCatalog.

Common situations: Upgrading Spark/Iceberg against an older catalog backend that predates view support; configuring a custom catalog implementation that only extends TableCatalog; running REPLACE VIEW in tests against HadoopCatalog which lacks view 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/7ba3159bce84e8fc. Report an issue: GitHub.