apache/iceberg · error · java.lang.UnsupportedOperationException

Namespaces are not supported by catalog

Error message

Namespaces are not supported by catalog: <catalogName>

What it means

createNamespace requires the underlying catalog to implement SupportsNamespaces. When asNamespaceCatalog is null, SparkCatalog throws UnsupportedOperationException stating namespaces are not supported by the given catalog name — the operation is impossible for this backend.

Solutions

1. Configure a namespace-capable catalog (HadoopCatalog, JDBCCatalog, RESTCatalog, NessieCatalog, etc.)
2. Check `catalog instanceof SupportsNamespaces` before issuing namespace operations
3. Create tables with fully qualified identifiers that the backend does support, or pre-create namespaces outside Spark

Example fix

// before
spark.conf.set("spark.sql.catalog.local", "com.example.FlatTableCatalog"); spark.sql("CREATE NAMESPACE local.db");
// after
spark.conf.set("spark.sql.catalog.local", "org.apache.iceberg.spark.SparkCatalog"); spark.conf.set("spark.sql.catalog.local.warehouse", "/tmp/warehouse"); spark.sql("CREATE NAMESPACE local.db");

if (!(icebergCatalog instanceof SupportsNamespaces)) { throw new IllegalStateException("catalog " + catalogName + " does not support namespaces"); }

boolean canCreateNamespace(CatalogPlugin c) { return c instanceof SupportsNamespaces; }

try { spark.sql("CREATE NAMESPACE ns"); } catch (UnsupportedOperationException e) { /* reconfigure catalog or skip */ }

When it happens

Trigger: CREATE NAMESPACE against a catalog whose implementation only implements TableCatalog (e.g. custom or limited catalog plugins registered via spark.sql.catalog.<name>).

Common situations: Misconfigured catalog class; using the session catalog with a namespace-less backend; assuming Hadoop-style hierarchical namespaces work everywhere.

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

• Cannot apply unknown namespace change
• Cannot apply unknown namespace change
• Namespaces are not supported by catalog
• Namespaces are not supported by catalog
• Namespaces are not supported by catalog

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

Appendix: source

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

  @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)