apache/iceberg · error · NoSuchNamespaceException

Namespace does not exist: %s

Error message

Namespace does not exist: %s

What it means

listNamespaces(namespace) with a non-empty namespace first checks that the root namespace content actually exists on the current reference. If the content lookup returns null, it throws NoSuchNamespaceException 'Namespace does not exist'. This is a client-side existence check before issuing the filtered entries query.

Source

Thrown at nessie/src/main/java/org/apache/iceberg/nessie/NessieIcebergClient.java:281

    }
  }

  public List<Namespace> listNamespaces(Namespace namespace) throws NoSuchNamespaceException {
    try {
      String filter = "entry.contentType == 'NAMESPACE' && ";
      if (namespace.isEmpty()) {
        filter += "size(entry.keyElements) == 1";
      } else {
        org.projectnessie.model.Namespace root =
            org.projectnessie.model.Namespace.of(namespace.levels());
        Content existing =
            api.getContent()
                .reference(getReference())
                .key(root.toContentKey())
                .get()
                .get(root.toContentKey());
        if (existing == null) {
          throw new NoSuchNamespaceException("Namespace does not exist: %s", namespace);
        }

        filter +=
            String.format(
                Locale.ROOT,
                "size(entry.keyElements) == %d && entry.encodedKey.startsWith('%s.')",
                root.getElementCount() + 1,
                root.name());
      }
      List<ContentKey> entries =
          withReference(api.getEntries()).filter(filter).stream()
              .map(EntriesResponse.Entry::getName)
              .collect(Collectors.toList());
      if (entries.isEmpty()) {
        return Collections.emptyList();
      }
      GetContentBuilder getContent = withReference(api.getContent());
      entries.forEach(getContent::key);

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Call catalog.namespaceExists(namespace) or listNamespaces(Namespace.empty()) to see which top-level namespaces actually exist before drilling down.
  2. Correct the namespace spelling/level structure in the caller.
  3. Verify you are connected to the intended branch/ref where the namespace was created.

Example fix

// before
List<Namespace> children = catalog.listNamespaces(Namespace.of("a", "b")); // a.b may not exist
// after
if (catalog.namespaceExists(Namespace.of("a", "b"))) {
  List<Namespace> children = catalog.listNamespaces(Namespace.of("a", "b"));
}
Defensive patterns

Strategy: validation

Validate before calling

if (!catalog.namespaceExists(namespace)) {
  throw new IllegalArgumentException("Namespace not found: " + namespace);
}
List<Namespace> children = catalog.listNamespaces(namespace);

Try / catch

try {
  return catalog.listNamespaces(ns);
} catch (NoSuchNamespaceException e) {
  return Collections.emptyList();
}

Prevention

When it happens

Trigger: Calling Catalog.listNamespaces(Namespace.of("a","b")) where namespace 'a.b' was never created or was already dropped on the current ref.

Common situations: Typo in namespace name or wrong separator handling (dots vs multi-level); listing children under a namespace that exists on a different branch; listing after another job dropped the namespace.

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/26cf36ad38e75585. Report an issue: GitHub.