apache/iceberg · error · java.lang.UnsupportedOperationException

Cannot apply unknown namespace change

Error message

Cannot apply unknown namespace change: %s

What it means

SparkCatalog.alterNamespace throws UnsupportedOperationException when a NamespaceChange is not SetProperty or RemoveProperty. Only property set/remove changes are currently supported for namespaces; any other change kind is rejected with the change's toString in the message.

Solutions

  1. Restrict namespace changes to SET PROPERTIES and UNSET PROPERTIES
  2. Set namespace comment via a property (e.g. 'comment') instead of a comment clause
  3. Upgrade Iceberg's Spark runtime to a version that handles the change type you need

Example fix

// before
spark.sql("ALTER NAMESPACE prod.db SET COMMENT 'sales data'"); // may hit unsupported change
// after
spark.sql("ALTER NAMESPACE prod.db SET PROPERTIES ('comment'='sales data')");
Defensive patterns

Strategy: validation

Validate before calling

boolean supported = java.util.stream.Stream.of(changes)
    .allMatch(c -> c instanceof NamespaceChange.SetProperty
        || c instanceof NamespaceChange.RemoveProperty);
if (!supported) throw new IllegalArgumentException("Only property changes supported");

Type guard

boolean isSupportedChange(NamespaceChange c) {
  return c instanceof NamespaceChange.SetProperty || c instanceof NamespaceChange.RemoveProperty;
}

Try / catch

try {
  catalog.alterNamespace(namespace, changes);
} catch (UnsupportedOperationException e) {
  // unsupported change type: fall back to property-based equivalent
}

Prevention

When it happens

Trigger: Passing a NamespaceChange type other than SetProperty/RemoveProperty to alterNamespace — typically from Spark SQL ALTER NAMESPACE ... with an unsupported clause that maps to a newer change type not handled by this Spark 3.5 code path.

Common situations: Running ALTER NAMESPACE with comment/rename semantics against a catalog whose connector version doesn't support them; custom code constructing NamespaceChange variants that SparkCatalog doesn't handle.

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/9de60e28d3199bdb. Report an issue: GitHub.

Appendix: source

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

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

  @Override
  public void alterNamespace(String[] namespace, NamespaceChange... changes)
      throws NoSuchNamespaceException {
    if (asNamespaceCatalog != null) {
      Map<String, String> updates = Maps.newHashMap();
      Set<String> removals = Sets.newHashSet();
      for (NamespaceChange change : changes) {
        if (change instanceof NamespaceChange.SetProperty) {
          NamespaceChange.SetProperty set = (NamespaceChange.SetProperty) change;
          updates.put(set.property(), set.value());
        } else if (change instanceof NamespaceChange.RemoveProperty) {
          removals.add(((NamespaceChange.RemoveProperty) change).property());
        } else {
          throw new UnsupportedOperationException(
              "Cannot apply unknown namespace change: " + change);
        }
      }

      try {
        if (!updates.isEmpty()) {
          asNamespaceCatalog.setProperties(Namespace.of(namespace), updates);
        }

        if (!removals.isEmpty()) {
          asNamespaceCatalog.removeProperties(Namespace.of(namespace), removals);
        }

      } catch (org.apache.iceberg.exceptions.NoSuchNamespaceException e) {
        throw new NoSuchNamespaceException(namespace);
      }
    } else {
      throw new NoSuchNamespaceException(namespace);

View on GitHub (pinned to 86d9c8fc54)