apache/iceberg · error · UncheckedIOException

Cannot load namespace '%s': ref '%s' is no longer valid.

Error message

Cannot load namespace '%s': ref '%s' is no longer valid.

What it means

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.

Source

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

  private static void checkNamespaceIsValid(Namespace namespace) {
    if (namespace.isEmpty()) {
      throw new NoSuchNamespaceException("Invalid namespace: %s", namespace);
    }
  }

  public Map<String, String> loadNamespaceMetadata(Namespace namespace)
      throws NoSuchNamespaceException {
    checkNamespaceIsValid(namespace);

    ContentKey key = ContentKey.of(namespace.levels());
    try {
      Map<ContentKey, Content> contentMap = withReference(api.getContent()).key(key).get();
      return unwrapNamespace(contentMap.get(key))
          .orElseThrow(
              () -> new NoSuchNamespaceException("Namespace does not exist: %s", namespace))
          .getProperties();
    } catch (NessieNotFoundException e) {
      throw new UncheckedIOException(
          String.format(
              "Cannot load namespace '%s': ref '%s' is no longer valid.",
              namespace, getRef().getName()),
          e);
    }
  }

  public boolean setProperties(Namespace namespace, Map<String, String> properties) {
    return updateProperties(namespace, props -> props.putAll(properties));
  }

  public boolean removeProperties(Namespace namespace, Set<String> properties) {
    return updateProperties(namespace, props -> props.keySet().removeAll(properties));
  }

  private boolean updateProperties(Namespace namespace, Consumer<Map<String, String>> action) {
    checkNamespaceIsValid(namespace);
    getRef().checkMutable();

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Verify the reference exists in Nessie (Nessie UI/API: list branches/tags) and recreate it if deleted, e.g. via Nessie CLI 'branch create'.
  2. Fix the catalog configuration so 'ref'/' Nessie reference' points to an existing branch (check warehouse/catalog properties).
  3. Re-create the IcebergCatalog/NessieCatalog instance after the reference is restored so the client re-resolves the ref.
  4. 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.

Example fix

// before
Catalog catalog = CatalogLoader.load(hadoopConf); // catalog ref 'feature-x' deleted
Map<String,String> props = catalog.loadNamespaceMetadata(ns); // throws UncheckedIOException
// after
NessieCatalog nc = (NessieCatalog) catalog;
if (!nessieApi.getAllReferences().get().getReferences().stream()
        .anyMatch(r -> r.getName().equals("feature-x"))) {
  nessieApi.createReference().sourceRefName("main").reference(Branch.of("feature-x", null)).create();
}
Map<String,String> props = catalog.loadNamespaceMetadata(ns);
Defensive patterns

Strategy: try-catch

Validate before calling

boolean refExists = nessieApi.getAllReferences().get().getReferences()
    .stream().anyMatch(r -> r.getName().equals(expectedRef));

Try / catch

try {
  Map<String,String> props = catalog.loadNamespaceMetadata(ns);
} catch (UncheckedIOException e) {
  if (e.getMessage() != null && e.getMessage().contains("no longer valid")) {
    recreateOrRepointRef(e); // restore branch or fix catalog config, then retry
  } else throw e;
}

Prevention

When it happens

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

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

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