apache/iceberg · error · IllegalArgumentException

Nessie ref '%s' does not exist

Error message

Nessie ref '%s' does not exist

What it means

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.

Source

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

  }

  private UpdateableReference loadReference(String requestedRef, String hash) {
    try {
      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);

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Create the ref on the server: via Nessie UI/API, e.g. POST a branch named as configured, or via the Nessie CLI.
  2. Correct the catalog property 'ref' to an existing branch or tag name.
  3. List available refs (curl http://nessie:19120/api/v2/trees) to see valid names.

Example fix

// before
properties.put("ref", "main_dev"); // does not exist
// after
properties.put("ref", "main"); // existing branch
// or create it first:
// curl -X PUT http://nessie:19120/api/v2/trees/main_dev -d '{...}'
Defensive patterns

Strategy: validation

Validate before calling

try (NessieApiV1 api = NessieClientBuilder.createClientBuilderFromSystemSettings().build(NessieApiV1.class)) {
  api.reference().refName(configuredRef).get(); // throws NessieNotFoundException if missing
}

Try / catch

try {
  catalog.initialize(name, props, conf);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Nessie ref '")) {
    // fix ref name or create the branch, then retry
    props.put("ref", "main");
    catalog.initialize(name, props, conf);
  } else throw e;
}

Prevention

When it happens

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

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

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