apache/iceberg · error · UnsupportedOperationException

Altering a view is not supported by catalog: catalogName

Error message

Altering a view is not supported by catalog: catalogName

What it means

SparkCatalog.alterView throws UnsupportedOperationException when the wrapped catalog does not implement the Iceberg ViewCatalog interface (asViewCatalog is null). Views (including their properties) cannot be altered by table-only catalogs, so the operation is rejected with the catalog name in the message.

Solutions

Use a view-capable catalog (HiveCatalog, JdbcCatalog, RESTCatalog, NessieCatalog) for spark.sql.catalog.<name>.
Move the view to a catalog that supports view properties before altering.
Store view metadata elsewhere (e.g. table properties on a backing table or an external metadata store) if a table-only catalog must be used.
Implement org.apache.iceberg.catalog.ViewCatalog in the custom catalog to support ALTER VIEW.

Example fix

// before
spark.conf.set("spark.sql.catalog.gov", "org.apache.iceberg.hadoop.HadoopCatalog");
spark.sql("ALTER VIEW gov.ns.v SET TBLPROPERTIES ('owner'='data-team')"); // fails

// after
spark.conf.set("spark.sql.catalog.gov", "org.apache.iceberg.jdbc.JdbcCatalog");
spark.sql("ALTER VIEW gov.ns.v SET TBLPROPERTIES ('owner'='data-team')");

Defensive patterns

Strategy: validation

Validate before calling

Catalog catalog = Spark3Util.loadIcebergCatalog(spark, catalogName);
if (!(catalog instanceof ViewCatalog)) {
  throw new IllegalStateException("ALTER VIEW unsupported on catalog " + catalogName);
}

Type guard

boolean supportsViewAlter(Catalog catalog) {
  return catalog instanceof org.apache.iceberg.catalog.ViewCatalog;
}

Try / catch

try {
  spark.sql("ALTER VIEW " + ident + " SET TBLPROPERTIES ('owner'='data-team')");
} catch (UnsupportedOperationException e) {
  if (e.getMessage().contains("Altering a view is not supported")) {
    // move view to a view-capable catalog or record metadata elsewhere
  }
}

Prevention

Verify ViewCatalog support before running governance scripts that ALTER views.
Keep view objects in catalogs that support view properties (JDBC/REST/Hive/Nessie).
Gate metadata-management jobs on catalog capability checks.
For custom catalogs, implement ViewCatalog before enabling view workflows.

When it happens

Trigger: Executing ALTER VIEW ... SET/UNSET TBLPROPERTIES (routed to alterView at SparkCatalog.java:694) against a catalog configured without ViewCatalog support, e.g. spark.sql.catalog.<name>=org.apache.iceberg.hadoop.HadoopCatalog or a custom Catalog implementation.

Common situations: Governance scripts that set owner/description properties on all objects hitting a HadoopCatalog-backed session; view maintenance jobs copied from Hive-catalog setups; custom in-house catalogs lacking ViewCatalog.

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

Appendix: source

Thrown at spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java:721

            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;
            verifyNonReservedPropertyIsUnset(remove.property());
            updateViewProperties.remove(remove.property());
          }
        }

        updateViewProperties.commit();

        return new SparkView(catalogName, view);
      } catch (org.apache.iceberg.exceptions.NoSuchViewException e) {
        throw new NoSuchViewException(ident);
      }
    }

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

  private static void verifyNonReservedProperty(String property, String errorMsg) {
    if (SparkView.RESERVED_PROPERTIES.contains(property)) {
      throw new UnsupportedOperationException(String.format(errorMsg, property));
    }
  }

  private static void verifyNonReservedPropertyIsUnset(String property) {
    verifyNonReservedProperty(property, "Cannot unset reserved property: '%s'");
  }

  private static void verifyNonReservedPropertyIsSet(String property) {
    verifyNonReservedProperty(property, "Cannot set reserved property: '%s'");
  }

  @Override

View on GitHub (pinned to 86d9c8fc54)