apache/iceberg · error · IllegalArgumentException

Nessie does not have an existing default branch. Either conf

Error message

Nessie does not have an existing default branch. Either configure an alternative ref via '%s' or create the default branch on the server.

What it means

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.

Source

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

      Reference ref =
          requestedRef == null
              ? api.getDefaultBranch()
              : api.getReference().refName(requestedRef).get();
      if (hash != null) {
        if (ref instanceof Branch) {
          ref = Branch.of(ref.getName(), hash);
        } else {
          ref = Tag.of(ref.getName(), hash);
        }
      }
      return new UpdateableReference(ref, hash != null);
    } catch (NessieNotFoundException ex) {
      if (requestedRef != null) {
        throw new IllegalArgumentException(
            String.format("Nessie ref '%s' does not exist", requestedRef), ex);
      }

      throw new IllegalArgumentException(
          String.format(
              "Nessie does not have an existing default branch. "
                  + "Either configure an alternative ref via '%s' or create the default branch on the server.",
              NessieConfigConstants.CONF_NESSIE_REF),
          ex);
    }
  }

  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) {

View on GitHub (pinned to 86d9c8fc54)

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).

Example fix

// before
Map<String, String> props = Map.of("uri", "http://nessie:19120/api/v2"); // default branch missing
// after
Map<String, String> props = Map.of(
    "uri", "http://nessie:19120/api/v2",
    "ref", "my-existing-branch");

Defensive patterns

Strategy: validation

Validate before calling

try (NessieApiV1 api = ...build(NessieApiV1.class)) {
  api.reference().refName("main").get(); // ensure default branch exists or set 'ref' explicitly
}

Try / catch

try {
  catalog.initialize(name, props, conf);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("default branch")) {
    // create the default branch server-side, then retry
    nessieCli.createBranch("main");
    catalog.initialize(name, props, conf);
  } else throw e;
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

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