apache/iceberg · error · UnsupportedOperationException

Namespaces are not supported by catalog: ${catalogName}

Error message

Namespaces are not supported by catalog: ${catalogName}

What it means

Thrown by SparkCatalog.createNamespace when the underlying Iceberg catalog does not implement SupportsNamespaces (asNamespaceCatalog is null). Namespaces are a capability of the catalog, and this catalog cannot create them, so an UnsupportedOperationException naming the catalog is raised.

Source

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

  @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

Configure a namespace-capable catalog (HiveCatalog, HadoopCatalog, REST, Nessie, JDBC)
Create the equivalent namespace/database through the external system (e.g. Hive 'CREATE DATABASE') instead of via this catalog
Skip namespace creation when SupportsNamespaces is not implemented
Document per-catalog capabilities so setup scripts branch accordingly

Example fix

// before
spark.sql("CREATE NAMESPACE my_catalog.prod")
// after
if (sparkCatalog instanceof SupportsNamespaces) {
  spark.sql("CREATE NAMESPACE IF NOT EXISTS my_catalog.prod");
} else {
  // create the database in the external metastore instead
  hiveClient.createDatabase("prod");
}

Defensive patterns

Strategy: type-guard

Validate before calling

if (!(catalog instanceof SupportsNamespaces)) {
  throw new UnsupportedOperationException(
      "Namespaces are not supported by catalog: " + catalog.name());
}

Type guard

boolean canCreateNamespaces(CatalogPlugin catalog) {
  return catalog instanceof SupportsNamespaces;
}

Try / catch

try {
  nsc.createNamespace(ns, metadata);
} catch (UnsupportedOperationException e) {
  log.error("Namespace creation unsupported on {}; use external metastore", catalogName, e);
  throw e;
}

Prevention

Verify SupportsNamespaces before namespace creation logic
Route namespace provisioning to the external system (Hive metastore, Nessie) for catalogs that lack it
Configure namespace-capable catalog types in Spark config
Keep a capability matrix of catalogs used in your platform

When it happens

Trigger: CREATE NAMESPACE or createNamespace() against a catalog configured via spark.sql.catalog.<name> whose implementation is table-only (no SupportsNamespaces), e.g. a custom catalog or certain glue/JDBC setups lacking namespace support.

Common situations: Applying a generic namespace bootstrap script across heterogeneous catalogs; using an external catalog that manages its own databases/locations and disallows namespace creation from Iceberg.

Related errors

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