apache/iceberg · error · UnsupportedOperationException

View operations are not supported by catalog

Error message

View operations are not supported by catalog: ${catalogName}

What it means

Guard in SparkCatalog.commitView: the operation was a view commit (create/replace), but the wrapped catalog does not implement ViewCatalog (asViewCatalog is null). Since view mutations need view-catalog support, the commit is refused rather than silently dropping the view change.

Solutions

  1. Configure a catalog that supports views, e.g. spark.sql.catalog.my_cat=org.apache.iceberg.spark.SparkCatalog with a Hive/REST/JDBC backend
  2. Upgrade to an Iceberg catalog implementation with ViewCatalog support
  3. Store views in Spark's built-in session catalog instead
Defensive patterns

Strategy: validation

Validate before calling

if (!(sparkCatalog instanceof ViewCatalog)) {
  throw new IllegalStateException("Configure a view-capable Iceberg catalog");
}

Type guard

boolean canCreateViews = catalog instanceof ViewCatalog;

Try / catch

try { spark.sql("CREATE VIEW cat.db.v AS SELECT ..."); }
catch (UnsupportedOperationException e) { /* reconfigure catalog or use session catalog */ }

Prevention

When it happens

Trigger: CREATE VIEW / REPLACE VIEW / CREATE OR REPLACE VIEW executed against a catalog where asViewCatalog is null.

Common situations: Using HadoopCatalog or custom catalogs without view support; forgetting to configure a view-capable catalog (Hive/REST/N JDBC) in Spark session config.

Related errors

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

Appendix: source

Thrown at spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java:629

  private static RuntimeException unexpectedViewCommitException(
      String operation, Identifier ident, String failure, Exception cause) {
    return new IllegalStateException(
        String.format(
            "Cannot %s view %s because the underlying catalog %s", operation, ident, failure),
        cause);
  }

  private View commitView(Identifier ident, View view, ViewCommit viewCommit)
      throws ViewAlreadyExistsException, NoSuchNamespaceException, NoSuchViewException {
    Preconditions.checkArgument(view != null, "Invalid view metadata: null");

    if (null == asViewCatalog) {
      if (viewCommit == ViewCommit.REPLACE && tableExists(ident)) {
        throw new NoSuchViewException(ident);
      }

      throw new UnsupportedOperationException(
          "View operations are not supported by catalog: " + catalogName);
    }

    String[] currentNamespace = view.currentNamespace();
    Map<String, String> properties = view.properties();
    Schema icebergSchema = SparkSchemaUtil.convert(view.schema());
    Map<String, String> props = ViewUtil.createProperties(view);
    TableIdentifier viewIdentifier = buildIdentifier(ident);

    try {
      ViewBuilder builder =
          asViewCatalog
              .buildView(viewIdentifier)
              .withDefaultCatalog(view.currentCatalog())
              .withDefaultNamespace(Namespace.of(currentNamespace))
              .withQuery("spark", view.queryText())
              .withSchema(icebergSchema)
              .withLocation(properties.get(TableCatalog.PROP_LOCATION))

View on GitHub (pinned to 86d9c8fc54)