apache/iceberg · error · java.lang.UnsupportedOperationException

Namespaces are not supported by catalog

Error message

Namespaces are not supported by catalog: %s

What it means

SparkCatalog throws this UnsupportedOperationException when createNamespace is called but the underlying catalog does not implement NamespaceCatalog (asNamespaceCatalog is null). Not all Iceberg catalogs support hierarchical namespaces, so namespace operations are refused rather than silently misbehaving.

Solutions

1. Use a catalog implementation that supports namespaces (HadoopCatalog, HiveCatalog, JDBC, REST, Nessie)
2. Check the configured catalog class and its supported operations before issuing namespace DDL
3. Keep tables in the catalog's top level if namespaces are unsupported

Example fix

// before
spark.conf.set("spark.sql.catalog.custom", "com.example.FlatCatalog");
spark.sql("CREATE NAMESPACE custom.ns"); // throws
// after
spark.conf.set("spark.sql.catalog.custom", "org.apache.iceberg.spark.SparkCatalog");
spark.sql("CREATE NAMESPACE IF NOT EXISTS custom.ns");

// check capability before DDL
boolean supportsNamespaces = catalog instanceof org.apache.iceberg.catalog.NamespaceCatalog;
if (!supportsNamespaces) throw new IllegalStateException("Catalog does not support namespaces");

boolean supportsNamespaces(Object catalog) {
  return catalog instanceof org.apache.iceberg.catalog.NamespaceCatalog;
}

try {
  catalog.createNamespace(namespace, metadata);
} catch (UnsupportedOperationException e) {
  // catalog lacks namespace support: switch catalog impl or fail setup
}

When it happens

Trigger: CREATE NAMESPACE or ALTER NAMESPACE against a catalog configured via spark.sql.catalog.<name> whose implementation only supports flat table identifiers (no NamespaceCatalog), e.g. some custom/REST configs without namespace support.

Common situations: Pointing Spark at a catalog type that has no namespace concept (legacy key-value catalogs); copy-pasted catalog config where the implementation class lacks namespace support; assuming all Iceberg catalogs are hierarchical like HadoopCatalog.

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/838ae3da1c1930e1. Report an issue: GitHub.

Appendix: source

Thrown at spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java:521

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