{"record":{"id":"ff9a722f37980151","repo":"apache/iceberg","slug":"cannot-load-namespace-s-ref-s-is-no-longer","errorCode":null,"errorMessage":"Cannot load namespace '%s': ref '%s' is no longer valid.","messagePattern":"Cannot load namespace '(.+?)': ref '(.+?)' is no longer valid\\.","errorType":"exception","errorClass":"UncheckedIOException","httpStatus":500,"severity":"error","filePath":"nessie/src/main/java/org/apache/iceberg/nessie/NessieIcebergClient.java","lineNumber":386,"sourceCode":"  private static void checkNamespaceIsValid(Namespace namespace) {\n    if (namespace.isEmpty()) {\n      throw new NoSuchNamespaceException(\"Invalid namespace: %s\", namespace);\n    }\n  }\n\n  public Map<String, String> loadNamespaceMetadata(Namespace namespace)\n      throws NoSuchNamespaceException {\n    checkNamespaceIsValid(namespace);\n\n    ContentKey key = ContentKey.of(namespace.levels());\n    try {\n      Map<ContentKey, Content> contentMap = withReference(api.getContent()).key(key).get();\n      return unwrapNamespace(contentMap.get(key))\n          .orElseThrow(\n              () -> new NoSuchNamespaceException(\"Namespace does not exist: %s\", namespace))\n          .getProperties();\n    } catch (NessieNotFoundException e) {\n      throw new UncheckedIOException(\n          String.format(\n              \"Cannot load namespace '%s': ref '%s' is no longer valid.\",\n              namespace, getRef().getName()),\n          e);\n    }\n  }\n\n  public boolean setProperties(Namespace namespace, Map<String, String> properties) {\n    return updateProperties(namespace, props -> props.putAll(properties));\n  }\n\n  public boolean removeProperties(Namespace namespace, Set<String> properties) {\n    return updateProperties(namespace, props -> props.keySet().removeAll(properties));\n  }\n\n  private boolean updateProperties(Namespace namespace, Consumer<Map<String, String>> action) {\n    checkNamespaceIsValid(namespace);\n    getRef().checkMutable();","sourceCodeStart":368,"sourceCodeEnd":404,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/nessie/src/main/java/org/apache/iceberg/nessie/NessieIcebergClient.java#L368-L404","documentation":"NessieIcebergClient.loadNamespaceMetadata fetches the namespace object on the configured Nessie reference. When the Nessie API answers NessieNotFoundException (which, for getContent, refers to the reference itself, not the content), the client wraps it in an UncheckedIOException saying the ref '%s' is no longer valid. This means the named branch/tag the catalog is pinned to was deleted or renamed server-side.","triggerScenarios":"Calling catalog.loadNamespaceMetadata(namespace) (or a Namespace-level operation that resolves metadata) while the reference returned by getRef() (the configured branch or tag, e.g. 'main') no longer exists in the Nessie server; getContent() throws NessieNotFoundException.","commonSituations":"A teammate deleted or renamed the Nessie branch the catalog points to; the catalog was configured with a branch name with a typo; environments were migrated and old refs were garbage-collected; using a short-lived PR branch that has since been removed.","solutions":["Verify the reference exists in Nessie (Nessie UI/API: list branches/tags) and recreate it if deleted, e.g. via Nessie CLI 'branch create'.","Fix the catalog configuration so 'ref'/' Nessie reference' points to an existing branch (check warehouse/catalog properties).","Re-create the IcebergCatalog/NessieCatalog instance after the reference is restored so the client re-resolves the ref.","If the namespace itself is missing (ref is fine), check the NoSuchNamespaceException path — the namespace key does not exist on that branch; create it with createNamespace."],"exampleFix":"// before\nCatalog catalog = CatalogLoader.load(hadoopConf); // catalog ref 'feature-x' deleted\nMap<String,String> props = catalog.loadNamespaceMetadata(ns); // throws UncheckedIOException\n// after\nNessieCatalog nc = (NessieCatalog) catalog;\nif (!nessieApi.getAllReferences().get().getReferences().stream()\n        .anyMatch(r -> r.getName().equals(\"feature-x\"))) {\n  nessieApi.createReference().sourceRefName(\"main\").reference(Branch.of(\"feature-x\", null)).create();\n}\nMap<String,String> props = catalog.loadNamespaceMetadata(ns);","handlingStrategy":"try-catch","validationCode":"boolean refExists = nessieApi.getAllReferences().get().getReferences()\n    .stream().anyMatch(r -> r.getName().equals(expectedRef));","typeGuard":null,"tryCatchPattern":"try {\n  Map<String,String> props = catalog.loadNamespaceMetadata(ns);\n} catch (UncheckedIOException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"no longer valid\")) {\n    recreateOrRepointRef(e); // restore branch or fix catalog config, then retry\n  } else throw e;\n}","preventionTips":["Pre-flight check that the configured Nessie ref exists before starting jobs.","Avoid deleting branches while readers/writers are attached to them.","Keep catalog ref configuration in one reviewed place; validate ref names at deploy time.","Distinguish 'ref invalid' (UncheckedIOException) from 'namespace missing' (NoSuchNamespaceException) in error handling."],"tags":["nessie","catalog","namespace","reference-not-found","configuration"],"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"}