apache/iceberg · error · NoSuchNamespaceException

Unable to list %ss due to missing ref '%s'

Error message

Unable to list %ss due to missing ref '%s'

What it means

NessieIcebergClient.listContents lists tables or views in a namespace by fetching entries on the current ref. If the ref disappears (deleted/renamed between construction and the call), NessieNotFoundException is wrapped as a NoSuchNamespaceException with this message — the ref name is reported as if it were a missing namespace so the Iceberg Namespace API can surface the failure.

Source

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

  public List<TableIdentifier> listTables(Namespace namespace) {
    return listContents(namespace, Content.Type.ICEBERG_TABLE);
  }

  public List<TableIdentifier> listViews(Namespace namespace) {
    return listContents(namespace, Content.Type.ICEBERG_VIEW);
  }

  /** Lists Iceberg table or view from the given namespace */
  private List<TableIdentifier> listContents(Namespace namespace, Content.Type type) {
    try {
      return withReference(api.getEntries()).get().getEntries().stream()
          .filter(namespacePredicate(namespace))
          .filter(e -> type.equals(e.getType()))
          .map(this::toIdentifier)
          .collect(Collectors.toList());
    } catch (NessieNotFoundException ex) {
      throw new NoSuchNamespaceException(
          ex,
          "Unable to list %ss due to missing ref '%s'",
          NessieUtil.contentTypeString(type).toLowerCase(Locale.ROOT),
          getRef().getName());
    }
  }

  private Predicate<EntriesResponse.Entry> namespacePredicate(Namespace ns) {
    if (ns == null) {
      return e -> true;
    }

    final List<String> namespace = Arrays.asList(ns.levels());
    return e -> {
      List<String> names = e.getName().getElements();

      if (names.size() <= namespace.size()) {
        return false;

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Recreate the ref (branch) on the Nessie server, or re-create the catalog pointing at an existing ref.
  2. Catch org.apache.iceberg.exceptions.NoSuchNamespaceException around listTables/listViews and refresh the client/ref before retrying.
  3. List available refs on the server to confirm the branch name and update the 'ref' config.

Example fix

// before
List<TableIdentifier> tables = catalog.listTables(namespace); // may throw
// after
try {
  List<TableIdentifier> tables = catalog.listTables(namespace);
} catch (NoSuchNamespaceException e) {
  // ref was deleted; recreate catalog against an existing ref
  catalog = NessieUtil.rebuildCatalogAgainstExistingRef(...);
}
Defensive patterns

Strategy: try-catch

Validate before calling

// before listing, confirm the ref still exists
api.reference().refName(currentRef).get();

Try / catch

try {
  tables = catalog.listTables(namespace);
} catch (NoSuchNamespaceException e) {
  if (e.getMessage().contains("missing ref")) {
    catalog = recreateCatalogAgainstExistingRef(); // refresh client
    tables = catalog.listTables(namespace);
  } else throw e;
}

Prevention

When it happens

Trigger: Calling listTables/listViews (via the catalog's listTables/listViews) while the underlying Nessie ref no longer exists — e.g. the branch was deleted after the catalog client was created, or a tag reference was used and entries are unavailable.

Common situations: Long-lived catalog handles against branches pruned by cleanup jobs; race between branch deletion by another process and listing; using an expired tag ref.

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/933473ff56808d97. Report an issue: GitHub.