What causes "Invalid namespace: %s" in apache/iceberg?

Provide at least one namespace level: Namespace.of("analytics").

apache/iceberg · error · NoSuchNamespaceException

Invalid namespace: %s

Error message

Invalid namespace: %s

What it means

A NoSuchNamespaceException thrown by RESTSessionCatalog.checkNamespaceIsValid when the given Namespace is empty. REST catalog namespace operations (create/namespace metadata/drop/list) require a non-empty namespace; an empty one is invalid and rejected client-side.

Source

Thrown at core/src/main/java/org/apache/iceberg/rest/RESTSessionCatalog.java:1418

    configResponse.validate();
    return configResponse;
  }

  private void checkIdentifierIsValid(TableIdentifier tableIdentifier) {
    if (tableIdentifier.namespace().isEmpty()) {
      throw new NoSuchTableException("Invalid table identifier: %s", tableIdentifier);
    }
  }

  private void checkViewIdentifierIsValid(TableIdentifier identifier) {
    if (identifier.namespace().isEmpty()) {
      throw new NoSuchViewException("Invalid view identifier: %s", identifier);
    }
  }

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

  public void commitTransaction(SessionContext context, List<TableCommit> commits) {
    Endpoint.check(endpoints, Endpoint.V1_COMMIT_TRANSACTION);
    List<UpdateTableRequest> tableChanges = Lists.newArrayListWithCapacity(commits.size());

    for (TableCommit commit : commits) {
      tableChanges.add(
          UpdateTableRequest.create(commit.identifier(), commit.requirements(), commit.updates()));
    }

    AuthSession contextualSession = authManager.contextualSession(context, catalogAuth);
    client
        .withAuthSession(contextualSession)
        .post(
            paths.commitTransaction(),
            new CommitTransactionRequest(tableChanges),

View on GitHub (pinned to 86d9c8fc54)

Solutions

Provide at least one namespace level: Namespace.of("analytics").
For listing top-level namespaces use listNamespaces() without arguments rather than passing an empty namespace.
Guard with namespace.isEmpty() before calling namespace operations.
Catch NoSuchNamespaceException if empty namespaces should be treated as 'namespace absent'.

Example fix

// before
catalog.createNamespace(Namespace.of());
// after
catalog.createNamespace(Namespace.of("staging"));

Defensive patterns

Strategy: validation

Validate before calling

if (namespace == null || namespace.isEmpty()) { throw new IllegalArgumentException("namespace must be non-empty (use listNamespaces() to list root)"); }

Try / catch

try { catalog.createNamespace(ns); } catch (NoSuchNamespaceException e) { /* invalid namespace */ }

Prevention

Never pass Namespace.empty() to REST namespace operations
Use the no-argument listNamespaces() for the root listing
Validate namespace.isEmpty() before calling namespace APIs
Ensure namespace parsing of user input never yields empty levels

When it happens

Trigger: Calling namespace APIs (createNamespace, namespaceExists, dropNamespace, loadNamespaceMetadata, listNamespaces with a namespace argument) passing Namespace.empty() or Namespace.of().

Common situations: Passing an empty namespace intentionally to mean 'root' — REST requires an explicit level; misconfigured default-namespace resolution; namespace parsed from an empty string.

Related errors

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