apache/iceberg · error · UnsupportedOperationException

Cannot apply unknown namespace change: ${change}

Error message

Cannot apply unknown namespace change: ${change}

What it means

alterNamespace was given a NamespaceChange type other than SetProperty or RemoveProperty (e.g. a future/unknown change kind), and the switch-style dispatch could not handle it, so UnsupportedOperationException('Cannot apply unknown namespace change: <change>') is thrown. Iceberg's namespace alteration supports only property set/remove operations.

Source

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

      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)

Solutions

1. Only issue NamespaceChange.setProperty/removeProperty changes; translate other intents accordingly.
2. Align Spark and Iceberg-Spark module versions so change types match what this handler supports.
3. Filter/validate the change list before calling alterNamespace, rejecting unknown kinds up front.
4. If a new change kind is genuinely needed, extend the handler and file an Iceberg issue instead of passing it through.

Example fix

// before
catalog.alterNamespace(ns, someCustomChange); // UnsupportedOperationException

// after
if (change instanceof NamespaceChange.SetProperty || change instanceof NamespaceChange.RemoveProperty) {
  catalog.alterNamespace(ns, change);
} else {
  throw new IllegalArgumentException("Unsupported change kind: " + change.getClass().getName());
}

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

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

try {
  catalog.alterNamespace(ns, changes);
} catch (UnsupportedOperationException e) {
  // unknown change kind: pin matching Spark/Iceberg versions and translate the change
}

When it happens

Trigger: Calling catalog.alterNamespace(ns, change) with a custom or new NamespaceChange subclass; framework-generated changes from newer Spark/Iceberg versions not anticipated by this handler; code constructing NamespaceChange directly with an unexpected variant.

Common situations: Version drift where Spark emits a change type the pinned Iceberg handler does not know; custom metadata layers building generic change pipelines that pass through unsupported change kinds; hand-written catalog abstraction layers.

Related errors

• No such namespace: %s
• NoSuchNamespaceException(namespace)
• NamespaceAlreadyExistsException(namespace)
• Namespaces are not supported by catalog: ${catalogName}
• e (wrapped NoSuchNamespaceException)

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