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

Thrown by SparkCatalog.replaceView when the catalog does not implement ViewCatalog (or the operation is otherwise unavailable). Iceberg signals that replacing views is not a supported operation for this catalog. It is a capability error and will occur for every replace attempt regardless of arguments.

Source

Thrown at spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java:692

        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

Point the catalog at a ViewCatalog-backed implementation (RESTCatalog, HiveCatalog, JdbcCatalog, Nessie)
Drop and re-create the view via the table path if views are impossible, or store the definition externally
Verify spark.sql.catalog.<name>.catalog-impl settings
Upgrade Iceberg Spark runtime if the backing catalog gained view support in a newer version

Example fix

// before
spark.sql("CREATE OR REPLACE VIEW prod.db.v AS SELECT ...") // Replacing a view is not supported by catalog: prod
// after
spark.conf.set("spark.sql.catalog.prod.catalog-impl", "org.apache.iceberg.jdbc.JdbcCatalog")
spark.sql("CREATE OR REPLACE VIEW prod.db.v AS SELECT ...")

Defensive patterns

Strategy: type-guard

Validate before calling

if (!(catalog instanceof ViewCatalog)) {
  LOG.error("Catalog {} cannot replace views; reconfigure catalog-impl", catalogName);
  return;
}

Type guard

static boolean replaceViewSupported(Object catalog) {
  return catalog instanceof ViewCatalog;
}

Try / catch

try {
  spark.sql("CREATE OR REPLACE VIEW " + ident + " AS " + sql);
} catch (UnsupportedOperationException e) {
  if (e.getMessage().startsWith("Replacing a view is not supported")) {
    throw new ConfigurationException("Use a ViewCatalog-backed catalog or manage view SQL externally");
  }
  throw e;
}

Prevention

Assert ViewCatalog support at job startup before running replace DDL
Choose RESTCatalog/HiveCatalog/JdbcCatalog/Nessie for view workloads
Keep view definitions version-controlled externally if the catalog cannot host them
Re-run capability checks after catalog implementation upgrades

When it happens

Trigger: CREATE OR REPLACE VIEW or programmatic replaceView on a catalog lacking view support (asViewCatalog == null), e.g. SparkCatalog wrapping HadoopCatalog or a table-only custom catalog.

Common situations: Same configuration gap as view creation errors: table-only catalog plugins, wrong catalog-impl, environments where views were never part of the catalog's feature set.

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