apache/iceberg · error · UnsupportedOperationException

Namespaces are not supported by catalog: ${catalogName}

Error message

Namespaces are not supported by catalog: ${catalogName}

What it means

createNamespace was called on a SparkCatalog whose underlying Iceberg catalog does not implement SupportsNamespaces, so namespace creation is impossible and an UnsupportedOperationException with 'Namespaces are not supported by catalog: <name>' is thrown. This is a capability error, not a state error: the catalog simply cannot hold namespaces.

Source

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

  @Override
  public void createNamespace(String[] namespace, Map<String, String> metadata)
      throws NamespaceAlreadyExistsException {
    if (asNamespaceCatalog != null) {
      try {
        if (asNamespaceCatalog instanceof HadoopCatalog
            && DEFAULT_NS_KEYS.equals(metadata.keySet())) {
          // Hadoop catalog will reject metadata properties, but Spark automatically adds "owner".
          // If only the automatic properties are present, replace metadata with an empty map.
          asNamespaceCatalog.createNamespace(Namespace.of(namespace), ImmutableMap.of());
        } else {
          asNamespaceCatalog.createNamespace(Namespace.of(namespace), metadata);
        }
      } catch (AlreadyExistsException e) {
        throw new NamespaceAlreadyExistsException(namespace);
      }
    } else {
      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(

View on GitHub (pinned to 86d9c8fc54)

Solutions

Use a catalog that implements SupportsNamespaces (HiveCatalog, HadoopCatalog, REST/Nessie/JDBC with namespace support).
Check the catalog implementation class in spark.sql.catalog.<name> and verify its capabilities.
Reorganize the data layout to avoid namespaces if the catalog cannot represent them.
Wrap namespace DDL in a capability check and emit a clear user-facing message.

Example fix

// before
spark.sql("CREATE NAMESPACE mycatalog.analytics") // UnsupportedOperationException

// after
if (catalogNameSupportsNamespaces("mycatalog")) {
  spark.sql("CREATE NAMESPACE mycatalog.analytics")
} else {
  throw new IllegalStateException("Configure a SupportsNamespaces catalog for CREATE NAMESPACE")
}

Defensive patterns

Strategy: type-guard

Validate before calling

if (!(catalog instanceof org.apache.spark.sql.connector.catalog.SupportsNamespaces)) {
  throw new IllegalStateException("Catalog " + catalogName + " cannot create namespaces");
}

Type guard

boolean canCreateNamespaces(org.apache.spark.sql.connector.catalog.CatalogPlugin c) {
  return c instanceof org.apache.spark.sql.connector.catalog.SupportsNamespaces;
}

Try / catch

try {
  catalog.createNamespace(ns, metadata);
} catch (UnsupportedOperationException e) {
  // capability missing: reconfigure catalog or surface a clear user error
}

Prevention

Confirm the spark.sql.catalog.<name> implementation supports namespaces before designing schemas around them
Switch to HiveCatalog/HadoopCatalog/REST for hierarchical catalogs
Add capability checks in DDL runners
Avoid namespace DDL in generic multi-catalog tooling without a capability probe

When it happens

Trigger: CREATE NAMESPACE against a catalog whose underlying org.apache.iceberg.catalog.Catalog implements only TableCatalog; misconfigured spark.sql.catalog.<name> implementation class lacking namespace support; generic DDL runner executing CREATE NAMESPACE against every catalog type.

Common situations: Custom catalog plugins; path-based/flat catalogs; wiring Spark to a catalog type that stores only tables; users expecting all Iceberg catalogs to be hierarchical.

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