apache/iceberg · error · UnsupportedOperationException

Cannot apply unknown namespace change

Error message

Cannot apply unknown namespace change: ${change}

What it means

Thrown by SparkCatalog.alterNamespace when a NamespaceChange in the change list is neither SetProperty nor RemoveProperty. Only namespace property set/remove are supported by the Iceberg catalog abstraction; any other change type (now or added in future Spark versions) is rejected with an UnsupportedOperationException.

Solutions

1. Restrict namespace changes to NamespaceChange.SetProperty and RemoveProperty
2. After Spark upgrades, check the Iceberg SparkCatalog version supports new change types and upgrade Iceberg if needed
3. Implement the translation yourself via SupportsNamespaces.setProperties/removeProperties for supported kinds
4. File/track an Iceberg issue for the unsupported change type

Example fix

// before
nsc.alterNamespace(new String[]{"prod"}, new MyCustomNamespaceChange("k"));
// after
nsc.alterNamespace(new String[]{"prod"},
    NamespaceChange.setProperty("k", "v"));
// or for removal:
nsc.alterNamespace(new String[]{"prod"}, NamespaceChange.removeProperty("k"));

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

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

try {
  nsc.alterNamespace(ns, changes);
} catch (UnsupportedOperationException e) {
  log.error("Unsupported namespace change in {}", Arrays.toString(changes), e);
  throw new IllegalArgumentException("Only SetProperty/RemoveProperty are supported", e);
}

When it happens

Trigger: Calling alterNamespace with a change type outside SetProperty/RemoveProperty — e.g. a new Spark NamespaceChange subtype — or passing changes produced by newer Spark SQL syntax that this SparkCatalog version does not translate.

Common situations: Forward-compatibility issues after a Spark upgrade introducing new NamespaceChange kinds; custom code constructing NamespaceChange instances directly with unsupported subclasses.

Related errors

• Cannot apply unknown namespace change
• Cannot create table as the namespace does not exist
• e (wrapped NoSuchNamespaceException)
• Namespace already exists
• Namespace does not exist:

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

Appendix: source

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

      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)