{"record":{"id":"d0140f68a84b56ed","repo":"apache/iceberg","slug":"nessie-ref-s-does-not-exist","errorCode":null,"errorMessage":"Nessie ref '%s' does not exist","messagePattern":"Nessie ref '(.+?)' does not exist","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"nessie/src/main/java/org/apache/iceberg/nessie/NessieIcebergClient.java","lineNumber":139,"sourceCode":"  }\n\n  private UpdateableReference loadReference(String requestedRef, String hash) {\n    try {\n      Reference ref =\n          requestedRef == null\n              ? api.getDefaultBranch()\n              : api.getReference().refName(requestedRef).get();\n      if (hash != null) {\n        if (ref instanceof Branch) {\n          ref = Branch.of(ref.getName(), hash);\n        } else {\n          ref = Tag.of(ref.getName(), hash);\n        }\n      }\n      return new UpdateableReference(ref, hash != null);\n    } catch (NessieNotFoundException ex) {\n      if (requestedRef != null) {\n        throw new IllegalArgumentException(\n            String.format(\"Nessie ref '%s' does not exist\", requestedRef), ex);\n      }\n\n      throw new IllegalArgumentException(\n          String.format(\n              \"Nessie does not have an existing default branch. \"\n                  + \"Either configure an alternative ref via '%s' or create the default branch on the server.\",\n              NessieConfigConstants.CONF_NESSIE_REF),\n          ex);\n    }\n  }\n\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);","sourceCodeStart":121,"sourceCodeEnd":157,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/nessie/src/main/java/org/apache/iceberg/nessie/NessieIcebergClient.java#L121-L157","documentation":"NessieIcebergClient.loadReference resolves the configured Nessie ref (branch or tag) via the Nessie API. When the requested ref name cannot be found on the server, NessieNotFoundException is translated into this IllegalArgumentException so catalog clients fail fast with a clear message instead of leaking the Nessie API exception.","triggerScenarios":"Initializing the catalog (or any operation that constructs NessieIcebergClient) with property 'ref' (or NessieConfigConstants.CONF_NESSIE_REF) set to a branch/tag that does not exist on the Nessie server, including deleted or renamed refs.","commonSituations":"Typo in the ref name; branch deleted by another team/cleanup job; connecting a new environment to a server where that branch was never created; case-sensitivity mismatch in branch names.","solutions":["Create the ref on the server: via Nessie UI/API, e.g. POST a branch named as configured, or via the Nessie CLI.","Correct the catalog property 'ref' to an existing branch or tag name.","List available refs (curl http://nessie:19120/api/v2/trees) to see valid names."],"exampleFix":"// before\nproperties.put(\"ref\", \"main_dev\"); // does not exist\n// after\nproperties.put(\"ref\", \"main\"); // existing branch\n// or create it first:\n// curl -X PUT http://nessie:19120/api/v2/trees/main_dev -d '{...}'","handlingStrategy":"validation","validationCode":"try (NessieApiV1 api = NessieClientBuilder.createClientBuilderFromSystemSettings().build(NessieApiV1.class)) {\n  api.reference().refName(configuredRef).get(); // throws NessieNotFoundException if missing\n}","typeGuard":null,"tryCatchPattern":"try {\n  catalog.initialize(name, props, conf);\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().startsWith(\"Nessie ref '\")) {\n    // fix ref name or create the branch, then retry\n    props.put(\"ref\", \"main\");\n    catalog.initialize(name, props, conf);\n  } else throw e;\n}","preventionTips":["Verify ref names exist (via Nessie UI or GET /trees/{name}) before configuring","Watch for branch deletion jobs that may remove refs your catalogs depend on","Use the default branch or a long-lived branch rather than ephemeral tags in configs"],"tags":["nessie","ref","branch","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-14T11:17:12.474Z"}