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

Qualify the table with at least one namespace level: TableIdentifier.of(Namespace.of("ns"), "table").

apache/iceberg · error · NoSuchTableException

Invalid table identifier: %s

Error message

Invalid table identifier: %s

What it means

A NoSuchTableException thrown by RESTSessionCatalog.checkIdentifierIsValid when the table identifier's namespace is empty. REST catalog identifiers must have at least a one-level namespace; identifiers without one are invalid and rejected with this message before any request is made.

Source

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

          properties.get(CatalogProperties.WAREHOUSE_LOCATION));
    }

    ConfigResponse configResponse =
        client
            .withAuthSession(initialAuth)
            .get(
                ResourcePaths.config(),
                queryParams.build(),
                ConfigResponse.class,
                RESTUtil.configHeaders(properties),
                ErrorHandlers.configErrorHandler());
    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());

View on GitHub (pinned to 86d9c8fc54)

Solutions

Qualify the table with at least one namespace level: TableIdentifier.of(Namespace.of("ns"), "table").
Apply the catalog's default namespace from its configuration when the user gives an unqualified name.
Guard with identifier.namespace().isEmpty() before calling catalog table operations.
Catch NoSuchTableException if you intend to treat invalid identifiers as 'table absent'.

Example fix

// before
TableIdentifier ident = TableIdentifier.of(Namespace.of(), "events");
catalog.loadTable(ident);
// after
TableIdentifier ident = TableIdentifier.of(Namespace.of("analytics"), "events");
catalog.loadTable(ident);

Defensive patterns

Strategy: validation

Validate before calling

if (identifier == null || identifier.namespace().isEmpty()) { throw new IllegalArgumentException("table identifier requires a non-empty namespace: " + identifier); }

Try / catch

try { catalog.loadTable(ident); } catch (NoSuchTableException e) { /* invalid or missing identifier */ }

Prevention

Always construct TableIdentifier with Namespace.of at least one level
Resolve unqualified user names against the catalog default namespace
Validate identifier.namespace().isEmpty() before any REST table call
Avoid parsing identifiers from raw strings without namespace handling

When it happens

Trigger: Calling table APIs (loadTable, tableExists, dropTable, registerTable, etc.) with TableIdentifier.of(...) built from an empty or zero-level namespace, e.g. TableIdentifier.of("table") is fine but a Namespace.of() (empty) identifier is not.

Common situations: Parsing user-supplied dot-separated names where the namespace part was dropped; building identifiers programmatically with an empty Namespace; SQL front-ends passing unqualified table names without applying the catalog's default namespace.

Related errors

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