apache/iceberg · error · NoSuchNamespaceException

Namespace not found: ${namespace}

Error message

Namespace not found: ${namespace}

What it means

Thrown by SparkCatalog.listNamespaces(namespace) when the configured Iceberg catalog implements SupportsNamespaces but reports that the given parent namespace does not exist. Spark translates the Iceberg NoSuchNamespaceException into Spark's NoSuchNamespaceException.

Source

Thrown at spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java:482

  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 listing its children
2. List top-level namespaces (listNamespaces() with no args) to see what actually exists
3. Correct the namespace spelling/qualifier in the query
4. Create the namespace first with 'CREATE NAMESPACE <ns>'

Example fix

// before
spark.sql("SHOW NAMESPACES IN prod.billing")
// after
if (sparkCatalog.namespaceExists(new String[]{"prod", "billing"})) {
  spark.sql("SHOW NAMESPACES IN prod.billing");
} else {
  spark.sql("CREATE NAMESPACE prod.billing");
  spark.sql("SHOW NAMESPACES IN prod.billing");
}

SupportsNamespaces nsc = (SupportsNamespaces) catalog;
if (!nsc.namespaceExists(namespace)) {
  throw new IllegalArgumentException("Namespace does not exist: " + String.join(".", namespace));
}

boolean isListable(SupportsNamespaces catalog, String[] ns) {
  return catalog.namespaceExists(ns);
}

try {
  catalog.listNamespaces(ns);
} catch (org.apache.spark.sql.catalyst.analysis.NoSuchNamespaceException e) {
  log.warn("Namespace {} not found; listing top-level instead", ns, e);
  String[][] fallback = catalog.listNamespaces();
}

When it happens

Trigger: Calling 'SHOW NAMESPACES IN <ns>' or listNamespaces(ns) where ns (or a parent level of it) does not exist in the catalog; typo in a multi-level namespace; the namespace was dropped by another process.

Common situations: Browsing sub-namespaces of a non-existent parent, typos like 'prodc' vs 'prod', connecting to a warehouse/database where the namespace was never created, cascading drops by another job.

Related errors

• No such namespace: %s
• Namespace does not exist:
• Namespace does not exist: %s
• Cannot list views for namespace. Namespace does not exist: %
• Namespace does not exist: %s

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