{"record":{"id":"d659381a94c0b1c2","repo":"apache/iceberg","slug":"nessie-does-not-have-an-existing-default-branch-e","errorCode":null,"errorMessage":"Nessie does not have an existing default branch. Either configure an alternative ref via '%s' or create the default branch on the server.","messagePattern":"Nessie does not have an existing default branch\\. Either configure an alternative ref via '(.+?)' or create the default branch on the server\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"nessie/src/main/java/org/apache/iceberg/nessie/NessieIcebergClient.java","lineNumber":143,"sourceCode":"      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);\n  }\n\n  /** Lists Iceberg table or view from the given namespace */\n  private List<TableIdentifier> listContents(Namespace namespace, Content.Type type) {","sourceCodeStart":125,"sourceCodeEnd":161,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/nessie/src/main/java/org/apache/iceberg/nessie/NessieIcebergClient.java#L125-L161","documentation":"loadReference catches NessieNotFoundException and, when no explicit ref was requested, checks the server's default branch. If even the default branch does not exist, the client throws this IllegalArgumentException telling you to configure an alternative ref (via the CONF_NESSIE_REF property) or create the default branch server-side.","triggerScenarios":"Constructing a NessieIcebergClient / initializing NessieCatalog with no 'ref' property against a Nessie server (or a specific database/project context) that has no default branch — e.g. a freshly initialized or wiped Nessie instance.","commonSituations":"Bootstrapping a brand-new Nessie server where 'main' hasn't been created; pointing at a different project/namespace context that has no branches; CI environments with ephemeral Nessie instances.","solutions":["Create the default branch on the server (e.g. via Nessie UI, CLI, or a PUT to /trees/main).","Set catalog property 'ref' to an existing branch so the client doesn't rely on the default branch.","Verify you're connecting to the intended Nessie instance/project (correct uri and namespace context)."],"exampleFix":"// before\nMap<String, String> props = Map.of(\"uri\", \"http://nessie:19120/api/v2\"); // default branch missing\n// after\nMap<String, String> props = Map.of(\n    \"uri\", \"http://nessie:19120/api/v2\",\n    \"ref\", \"my-existing-branch\");","handlingStrategy":"validation","validationCode":"try (NessieApiV1 api = ...build(NessieApiV1.class)) {\n  api.reference().refName(\"main\").get(); // ensure default branch exists or set 'ref' explicitly\n}","typeGuard":null,"tryCatchPattern":"try {\n  catalog.initialize(name, props, conf);\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().contains(\"default branch\")) {\n    // create the default branch server-side, then retry\n    nessieCli.createBranch(\"main\");\n    catalog.initialize(name, props, conf);\n  } else throw e;\n}","preventionTips":["Bootstrap a default branch on fresh Nessie instances before running jobs","Set an explicit 'ref' property so the client never depends on the default branch","For ephemeral CI environments, include branch creation in environment setup"],"tags":["nessie","branch","bootstrap","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"}