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 throws this from alterView when the underlying catalog does not implement ViewCatalog (asViewCatalog is null). View alteration is a catalog-level capability, so without a ViewCatalog backend, any ALTER VIEW statement fails with this UnsupportedOperationException.

Source

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

            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)

Solutions

Configure a catalog implementing ViewCatalog (REST, Hive, JDBC, Nessie).
Drop and recreate the view with updated definition/properties.
Set view properties via a supported engine/catalog once ViewCatalog is enabled.

Example fix

// before
spark.conf.set("spark.sql.catalog.local.catalog-impl", "org.apache.iceberg.hadoop.HadoopCatalog")
spark.sql("ALTER VIEW v SET TBLPROPERTIES ('k'='v')") // throws
// after
spark.conf.set("spark.sql.catalog.local.catalog-impl", "org.apache.iceberg.rest.RESTCatalog")
spark.sql("ALTER VIEW v SET TBLPROPERTIES ('k'='v')")

Defensive patterns

Strategy: validation

Validate before calling

if (!(catalogRef instanceof org.apache.iceberg.catalog.ViewCatalog)) {
  throw new IllegalStateException("ALTER VIEW requires a ViewCatalog-capable catalog");
}

Prevention

Prefer REST/Hive/JDBC/Nessie catalogs when view properties must be altered.
Avoid copying table TBLPROPERTIES workflows onto views without checking support.
Catch UnsupportedOperationException and fall back to drop/recreate.

When it happens

Trigger: Running 'ALTER VIEW name SET TBLPROPERTIES ...' or calling alterView() when the configured catalog implements only TableCatalog, e.g. HadoopCatalog or a custom catalog without view support.

Common situations: Using HadoopCatalog-backed Spark sessions; third-party catalog plugins predating view support; users unaware that view DDL requires a ViewCatalog-capable backend.

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