apache/iceberg · error · NoSuchNamespaceException

NoSuchNamespaceException(namespace)

Error message

NoSuchNamespaceException(namespace)

What it means

listNamespaces was called with a parent namespace that does not exist in the underlying Iceberg SupportsNamespaces catalog, so the Iceberg NoSuchNamespaceException was rethrown as Spark's NoSuchNamespaceException. There is also a fallback throw when the catalog does not implement SupportsNamespaces at all. Listing child namespaces requires the parent namespace itself to exist.

Source

Thrown at spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java:478

  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

1. Check namespaceExists(namespace) before calling listNamespaces with a parent.
2. Call listNamespaces() with no arguments to list top-level namespaces first.
3. Create the parent namespace with createNamespace before listing children.
4. If the catalog lacks namespace support, switch to a catalog implementing SupportsNamespaces (e.g. Hive, Hadoop, Nessie).

Example fix

// before
String[][] children = catalog.listNamespaces(new String[] {"analytics"}); // throws

// after
if (catalog.namespaceExists(new String[] {"analytics"})) {
  String[][] children = catalog.listNamespaces(new String[] {"analytics"});
}

if (catalog.namespaceExists(new String[] {"analytics"})) {
  // safe to list children
}

boolean isNamespaceCatalog(Object c) {
  return c instanceof org.apache.spark.sql.connector.catalog.SupportsNamespaces;
}

try {
  String[][] children = catalog.listNamespaces(ns);
} catch (NoSuchNamespaceException e) {
  // parent absent: create it or return empty result
}

When it happens

Trigger: Calling catalog.listNamespaces(namespace) where namespace (as String[]) is not a registered namespace; using SHOW NAMESPACES IN catalog under a nonexistent parent; the catalog is not a SupportsNamespaces (e.g. a flat path-based catalog) so any listNamespaces call throws.

Common situations: Discovering namespace hierarchy in metadata tools; HadoopCatalog users listing under a prefix that was never created; catalogs backed by stores without namespace support (listNamespaces always throws).

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

• NoSuchNamespaceException: <namespace>
• Cannot find default warehouse location: namespace %s does no
• Cannot find namespace %s
• Cannot use catalog %s(%s): not a TableCatalog
• SparkCachedTableCatalog does not support listing tables

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