apache/iceberg · error · UnsupportedOperationException

Altering a view is not supported by catalog

Error message

Altering a view is not supported by catalog: ${catalogName}

What it means

alterView() only works when the underlying catalog implements the ViewCatalog interface (asViewCatalog != null). If the configured catalog only supports tables (e.g. a catalog without view support), SparkCatalog throws this UnsupportedOperationException. The catalog implementation itself, not your SQL, lacks view-alteration capability.

Solutions

1. Switch the affected namespaces to a catalog implementation that supports views (HiveCatalog, JDBC catalog, REST catalog, Nessie, etc.) with a current Iceberg version
2. Check the catalog class configured via spark.sql.catalog.<name> and confirm it implements ViewCatalog
3. If view properties must change elsewhere, manage the view outside Spark or migrate the view to a view-capable catalog

Example fix

// before
spark.conf.set("spark.sql.catalog.local", "org.apache.iceberg.spark.SparkCatalog");
spark.conf.set("spark.sql.catalog.local.catalog-impl", "com.example.LegacyTableOnlyCatalog");
// after
spark.conf.set("spark.sql.catalog.local.catalog-impl", "org.apache.iceberg.jdbc.JdbcCatalog");

// Verify the catalog supports views before invoking view DDL
Catalog plugin = spark.sessionState().catalogManager().catalog(name).asCatalog();
if (!(plugin instanceof org.apache.spark.sql.connector.catalog.ViewCatalog)) {
  throw new IllegalStateException("Catalog " + name + " does not support views");
}

boolean supportsViews(Object catalogImpl) {
  return catalogImpl instanceof org.apache.iceberg.catalog.ViewCatalog;
}

try {
  catalog.alterView(ident, changes);
} catch (UnsupportedOperationException e) {
  if (e.getMessage().contains("not supported by catalog")) {
    // fall back to a view-capable catalog or surface a clear user error
  }
}

When it happens

Trigger: Calling SparkCatalog.alterView(ident, changes...) when the initialized catalog does not implement org.apache.iceberg.catalog.ViewCatalog, so asViewCatalog is null.

Common situations: Configuring a catalog type that predates view support (e.g. older HadoopCatalog-style setups or third-party catalogs without ViewCatalog); running a newer Spark Iceberg runtime against an older catalog implementation; ALTER VIEW against a custom catalog plugin.

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

• Altering a view is not supported by catalog:
• Altering a view is not supported by catalog
• Creating a view is not supported by catalog:
• Creating a view is not supported by catalog
• Creating a view is not supported by catalog: catalogName

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

Appendix: source

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

            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)