{"record":{"id":"933473ff56808d97","repo":"apache/iceberg","slug":"unable-to-list-ss-due-to-missing-ref-s","errorCode":null,"errorMessage":"Unable to list %ss due to missing ref '%s'","messagePattern":"Unable to list (.+?)s due to missing ref '(.+?)'","errorType":"exception","errorClass":"NoSuchNamespaceException","httpStatus":null,"severity":"error","filePath":"nessie/src/main/java/org/apache/iceberg/nessie/NessieIcebergClient.java","lineNumber":169,"sourceCode":"\n  public List<TableIdentifier> listTables(Namespace namespace) {\n    return listContents(namespace, Content.Type.ICEBERG_TABLE);\n  }\n\n  public List<TableIdentifier> listViews(Namespace namespace) {\n    return listContents(namespace, Content.Type.ICEBERG_VIEW);\n  }\n\n  /** Lists Iceberg table or view from the given namespace */\n  private List<TableIdentifier> listContents(Namespace namespace, Content.Type type) {\n    try {\n      return withReference(api.getEntries()).get().getEntries().stream()\n          .filter(namespacePredicate(namespace))\n          .filter(e -> type.equals(e.getType()))\n          .map(this::toIdentifier)\n          .collect(Collectors.toList());\n    } catch (NessieNotFoundException ex) {\n      throw new NoSuchNamespaceException(\n          ex,\n          \"Unable to list %ss due to missing ref '%s'\",\n          NessieUtil.contentTypeString(type).toLowerCase(Locale.ROOT),\n          getRef().getName());\n    }\n  }\n\n  private Predicate<EntriesResponse.Entry> namespacePredicate(Namespace ns) {\n    if (ns == null) {\n      return e -> true;\n    }\n\n    final List<String> namespace = Arrays.asList(ns.levels());\n    return e -> {\n      List<String> names = e.getName().getElements();\n\n      if (names.size() <= namespace.size()) {\n        return false;","sourceCodeStart":151,"sourceCodeEnd":187,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/nessie/src/main/java/org/apache/iceberg/nessie/NessieIcebergClient.java#L151-L187","documentation":"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.","triggerScenarios":"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.","commonSituations":"Long-lived catalog handles against branches pruned by cleanup jobs; race between branch deletion by another process and listing; using an expired tag ref.","solutions":["Recreate the ref (branch) on the Nessie server, or re-create the catalog pointing at an existing ref.","Catch org.apache.iceberg.exceptions.NoSuchNamespaceException around listTables/listViews and refresh the client/ref before retrying.","List available refs on the server to confirm the branch name and update the 'ref' config."],"exampleFix":"// before\nList<TableIdentifier> tables = catalog.listTables(namespace); // may throw\n// after\ntry {\n  List<TableIdentifier> tables = catalog.listTables(namespace);\n} catch (NoSuchNamespaceException e) {\n  // ref was deleted; recreate catalog against an existing ref\n  catalog = NessieUtil.rebuildCatalogAgainstExistingRef(...);\n}","handlingStrategy":"try-catch","validationCode":"// before listing, confirm the ref still exists\napi.reference().refName(currentRef).get();","typeGuard":null,"tryCatchPattern":"try {\n  tables = catalog.listTables(namespace);\n} catch (NoSuchNamespaceException e) {\n  if (e.getMessage().contains(\"missing ref\")) {\n    catalog = recreateCatalogAgainstExistingRef(); // refresh client\n    tables = catalog.listTables(namespace);\n  } else throw e;\n}","preventionTips":["Avoid holding long-lived catalog handles across ref-deletion operations","Refresh/rebuild the Nessie catalog after any branch lifecycle change","Use branch names that are excluded from automated cleanup policies"],"tags":["nessie","ref","namespace","list","not-found"],"backgroundTag":"resource-not-found","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}