apache/iceberg · error · NoSuchNamespaceException

Invalid namespace: %s

Error message

Invalid namespace: %s

What it means

checkNamespaceIsValid rejects an empty Namespace (zero levels). createNamespace, dropNamespace, loadNamespaceMetadata and updateProperties all require a concrete multi-level identifier, so passing Namespace.of() (or the root) throws NoSuchNamespaceException 'Invalid namespace'. Nessie namespaces map to content keys, which must have at least one element.

Source

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

        throw new UncheckedIOException(
            String.format("Cannot drop namespace '%s': %s", namespace, e.getMessage()), e);
      }
    } catch (NessieNotFoundException e) {
      LOG.error(
          "Cannot drop namespace '{}': ref '{}' is no longer valid.",
          namespace,
          getRef().getName(),
          e);
    } catch (BaseNessieClientServerException e) {
      throw new UncheckedIOException(
          String.format("Cannot drop namespace '%s': %s", namespace, e.getMessage()), e);
    }
    return false;
  }

  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.",

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Ensure the caller supplies at least one namespace level before invoking the catalog operation.
2. Fix the configuration that yields an empty namespace (e.g. warehouse/namespace property).
3. Guard with namespaceExists/isEmpty checks in application code before calling.

Example fix

// before
Namespace ns = Namespace.of(cfg.get("namespace", "")); // empty -> Invalid namespace
catalog.createNamespace(ns);
// after
String[] levels = cfg.getOrDefault("namespace", "").split("\\.");
Preconditions.checkArgument(levels.length > 0 && !levels[0].isEmpty(), "namespace required");
catalog.createNamespace(Namespace.of(levels));

if (namespace == null || namespace.isEmpty()) {
  throw new IllegalArgumentException("Namespace must have at least one level");
}
catalog.createNamespace(namespace);

static boolean isValidNamespace(Namespace ns) {
  return ns != null && !ns.isEmpty() && ns.levels().length > 0;
}

try {
  catalog.loadNamespaceMetadata(ns);
} catch (NoSuchNamespaceException e) {
  if (e.getMessage().contains("Invalid namespace")) {
    throw new IllegalArgumentException("Caller passed an empty namespace", e);
  }
  throw e;
}

When it happens

Trigger: Calling createNamespace/loadNamespaceMetadata/dropNamespace/setProperties/removeProperties with Namespace.root() or Namespace.of() — e.g. code paths that fall back to an empty namespace when configuration is missing.

Common situations: Config property for target namespace left blank; splitting an empty string; generic catalog tooling that passes the root namespace through to a Nessie catalog.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• invalid input for namespace %s, error message: %s
• Invalid table identifier: %s
• Invalid namespace: %s
• Invalid namespace update, cannot simultaneously set and remo
• Unable to list %ss due to missing ref '%s'

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/6f1ee3da1e8acc01. Report an issue: GitHub.