apache/iceberg · error · NoSuchNamespaceException

Cannot list child namespaces from '%s': ref '%s' is no longe

Error message

Cannot list child namespaces from '%s': ref '%s' is no longer valid.

What it means

Same stale-reference condition as the top-level variant, but raised when listing CHILD namespaces: the initial existence check or the filtered entries query for namespace X hit NessieNotFoundException because the pinned ref no longer exists. Message names the parent namespace and the dead ref.

Source

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

      if (entries.isEmpty()) {
        return Collections.emptyList();
      }
      GetContentBuilder getContent = withReference(api.getContent());
      entries.forEach(getContent::key);
      return getContent.get().values().stream()
          .map(v -> v.unwrap(org.projectnessie.model.Namespace.class))
          .filter(Optional::isPresent)
          .map(Optional::get)
          .map(v -> Namespace.of(v.getElements().toArray(new String[0])))
          .collect(Collectors.toList());
    } catch (NessieNotFoundException e) {
      if (namespace.isEmpty()) {
        throw new NoSuchNamespaceException(
            e,
            "Cannot list top-level namespaces: ref '%s' is no longer valid.",
            getRef().getName());
      }
      throw new NoSuchNamespaceException(
          e,
          "Cannot list child namespaces from '%s': ref '%s' is no longer valid.",
          namespace,
          getRef().getName());
    }
  }

  public boolean dropNamespace(Namespace namespace) throws NamespaceNotEmptyException {
    checkNamespaceIsValid(namespace);
    getRef().checkMutable();
    ContentKey key = ContentKey.of(namespace.levels());
    try {
      Map<ContentKey, Content> contentMap =
          api.getContent().reference(getReference()).key(key).get();
      Content existing = contentMap.get(key);
      if (existing != null && !existing.getType().equals(Content.Type.NAMESPACE)) {
        throw new NoSuchNamespaceException(
            "Content object with name '%s' is not a namespace.", namespace);

View on GitHub (pinned to 86d9c8fc54)

Solutions

Verify/recreate the reference on the Nessie server.
Correct the catalog 'ref' configuration.
Re-instantiate the catalog to re-resolve the reference hash.

Example fix

// before
catalog.listNamespaces(Namespace.of("staging")); // ref deleted -> throws
// after
if (Boolean.TRUE.equals(api.getAllReferences().get().getReferences().stream()
        .anyMatch(r -> r.getName().equals(refName)))) {
  catalog.listNamespaces(Namespace.of("staging"));
}

Defensive patterns

Strategy: validation

Validate before calling

if (!refExists(api, configuredRef)) return List.of();
return catalog.listNamespaces(parentNamespace);

Try / catch

try {
  return catalog.listNamespaces(parent);
} catch (NoSuchNamespaceException e) {
  if (e.getMessage().contains("no longer valid")) {
    throw new RefGoneException(e); // force caller to re-resolve ref
  }
  throw e;
}

Prevention

Check ref existence before namespace operations in batch jobs.
Avoid deleting branches during scheduled namespace scans.
Use default-branch fallback logic for resilience.

When it happens

Trigger: Calling Catalog.listNamespaces(Namespace.of("parent")) when the catalog's configured reference was deleted server-side.

Common situations: Branch deleted by another process while a job iterates namespaces; misconfigured ref name; tag expired.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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