{"record":{"id":"9c9ac9f359b96420","repo":"apache/iceberg","slug":"namespaces-are-not-supported-by-catalog-catalog","errorCode":null,"errorMessage":"Namespaces are not supported by catalog: ${catalogName}","messagePattern":"Namespaces are not supported by catalog: (.+?)","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java","lineNumber":522,"sourceCode":"\n  @Override\n  public void createNamespace(String[] namespace, Map<String, String> metadata)\n      throws NamespaceAlreadyExistsException {\n    if (asNamespaceCatalog != null) {\n      try {\n        if (asNamespaceCatalog instanceof HadoopCatalog\n            && DEFAULT_NS_KEYS.equals(metadata.keySet())) {\n          // Hadoop catalog will reject metadata properties, but Spark automatically adds \"owner\".\n          // If only the automatic properties are present, replace metadata with an empty map.\n          asNamespaceCatalog.createNamespace(Namespace.of(namespace), ImmutableMap.of());\n        } else {\n          asNamespaceCatalog.createNamespace(Namespace.of(namespace), metadata);\n        }\n      } catch (AlreadyExistsException e) {\n        throw new NamespaceAlreadyExistsException(namespace);\n      }\n    } else {\n      throw new UnsupportedOperationException(\n          \"Namespaces are not supported by catalog: \" + catalogName);\n    }\n  }\n\n  @Override\n  public void alterNamespace(String[] namespace, NamespaceChange... changes)\n      throws NoSuchNamespaceException {\n    if (asNamespaceCatalog != null) {\n      Map<String, String> updates = Maps.newHashMap();\n      Set<String> removals = Sets.newHashSet();\n      for (NamespaceChange change : changes) {\n        if (change instanceof NamespaceChange.SetProperty) {\n          NamespaceChange.SetProperty set = (NamespaceChange.SetProperty) change;\n          updates.put(set.property(), set.value());\n        } else if (change instanceof NamespaceChange.RemoveProperty) {\n          removals.add(((NamespaceChange.RemoveProperty) change).property());\n        } else {\n          throw new UnsupportedOperationException(","sourceCodeStart":504,"sourceCodeEnd":540,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java#L504-L540","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nspark.sql(\"CREATE NAMESPACE mycatalog.analytics\") // UnsupportedOperationException\n\n// after\nif (catalogNameSupportsNamespaces(\"mycatalog\")) {\n  spark.sql(\"CREATE NAMESPACE mycatalog.analytics\")\n} else {\n  throw new IllegalStateException(\"Configure a SupportsNamespaces catalog for CREATE NAMESPACE\")\n}","handlingStrategy":"type-guard","validationCode":"if (!(catalog instanceof org.apache.spark.sql.connector.catalog.SupportsNamespaces)) {\n  throw new IllegalStateException(\"Catalog \" + catalogName + \" cannot create namespaces\");\n}","typeGuard":"boolean canCreateNamespaces(org.apache.spark.sql.connector.catalog.CatalogPlugin c) {\n  return c instanceof org.apache.spark.sql.connector.catalog.SupportsNamespaces;\n}","tryCatchPattern":"try {\n  catalog.createNamespace(ns, metadata);\n} catch (UnsupportedOperationException e) {\n  // capability missing: reconfigure catalog or surface a clear user error\n}","preventionTips":["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"],"tags":["spark","catalog","namespace","unsupported-operation"],"backgroundTag":"unsupported-operation","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}