apache/iceberg · error · java.lang.UnsupportedOperationException

Cannot apply unknown namespace change

Error message

Cannot apply unknown namespace change: <change>

What it means

Spark's alterNamespace only supports SetProperty and RemoveProperty changes; any other namespace change type passed to SparkCatalog.alterNamespace is rejected with this UnsupportedOperationException. It is a guard against unknown/unimplemented change kinds.

Solutions

  1. Only build namespace changes via NamespaceChange.setProperty or NamespaceChange.removeProperty
  2. If the change is a rename or other unsupported operation, perform it directly against the underlying Iceberg catalog API instead of via Spark
  3. Update the Iceberg/Spark connector version if a newer change type was intended to be supported

Example fix

// before
NamespaceChange change = NamespaceChange.removeProperty("owner"); // wrong type elsewhere
// after
sparkCatalog.alterNamespace(ns, NamespaceChange.setProperty("owner", "team-a"));
Defensive patterns

Strategy: validation

Validate before calling

if (!(change instanceof NamespaceChange.SetProperty) && !(change instanceof NamespaceChange.RemoveProperty)) {
  throw new IllegalArgumentException("Unsupported namespace change: " + change);
}

Type guard

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

Prevention

When it happens

Trigger: Calling alterNamespace with a change instance that is neither NamespaceChange.SetProperty nor NamespaceChange.RemoveProperty (e.g. a custom or future change type).

Common situations: Custom catalog extensions or engine integrations forwarding unsupported namespace mutations (like renames) through the Spark catalog interface.

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

Appendix: source

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

      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)