What causes "NoSuchNamespaceException: " in apache/iceberg?

Verify the parent namespace exists with SHOW NAMESPACES or namespaceExists before listing children

apache/iceberg · error · org.apache.spark.sql.catalyst.analysis.NoSuchNamespaceException

NoSuchNamespaceException: <namespace>

Error message

NoSuchNamespaceException: <namespace>

What it means

listNamespaces(String[] namespace) looks up the child namespaces of the given namespace via a SupportsNamespaces catalog. If the catalog reports NoSuchNamespaceException the error is translated to Spark's NoSuchNamespaceException; the same error is also thrown when the catalog does not support namespaces at all.

Source

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

  public String[][] listNamespaces() {
    if (asNamespaceCatalog != null) {
      return asNamespaceCatalog.listNamespaces().stream()
          .map(Namespace::levels)
          .toArray(String[][]::new);
    }

    return new String[0][];
  }

  @Override
  public String[][] listNamespaces(String[] namespace) throws NoSuchNamespaceException {
    if (asNamespaceCatalog != null) {
      try {
        return asNamespaceCatalog.listNamespaces(Namespace.of(namespace)).stream()
            .map(Namespace::levels)
            .toArray(String[][]::new);
      } catch (org.apache.iceberg.exceptions.NoSuchNamespaceException e) {
        throw new NoSuchNamespaceException(namespace);
      }
    }

    throw new NoSuchNamespaceException(namespace);
  }

  @Override
  public boolean namespaceExists(String[] namespace) {
    return asNamespaceCatalog != null
        && asNamespaceCatalog.namespaceExists(Namespace.of(namespace));
  }

  @Override
  public Map<String, String> loadNamespaceMetadata(String[] namespace)
      throws NoSuchNamespaceException {
    if (asNamespaceCatalog != null) {
      try {
        return asNamespaceCatalog.loadNamespaceMetadata(Namespace.of(namespace));

View on GitHub (pinned to 86d9c8fc54)

Solutions

Verify the parent namespace exists with SHOW NAMESPACES or namespaceExists before listing children
Check the catalog implementation supports namespaces (implements SupportsNamespaces)
Correct the namespace spelling/case
Create the missing namespace first

Example fix

// before
spark.sql("SHOW NAMESPACES IN prod.missing")
// after
if (spark.sql("SHOW NAMESPACES IN prod").collectAsList().stream().anyMatch(r -> r.getString(1).equals("missing"))) { spark.sql("SHOW NAMESPACES IN prod.missing"); }

Defensive patterns

Strategy: validation

Validate before calling

boolean exists = spark.catalog().namespaceExists("prod.missing");

Try / catch

try { spark.sql("SHOW NAMESPACES IN prod.missing"); } catch (NoSuchNamespaceException e) { /* create or skip */ }

Prevention

Verify parent namespaces before listing children
Use catalogs implementing SupportsNamespaces
Standardize namespace naming to avoid typos

When it happens

Trigger: SHOW NAMESPACES under a parent namespace that does not exist, or using a catalog implementation that does not implement SupportsNamespaces (asNamespaceCatalog == null).

Common situations: Hadoop catalog with missing directory metadata; typo in the parent namespace; JDBC/REST catalog where the namespace was dropped.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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