apache/iceberg · error · NoSuchNamespaceException

%s

Error message

%s

What it means

NoSuchNamespaceException raised by loadNamespaceMetadata when client.load(datasetReference) throws IllegalArgumentException while loading the BigQuery dataset backing the namespace. The catalog translates that failure into a namespace-not-found error, since the dataset cannot be loaded.

Source

Thrown at bigquery/src/main/java/org/apache/iceberg/gcp/bigquery/BigQueryMetastoreCatalog.java:270

    if (!namespaceExists(namespace)) {
      throw new NoSuchNamespaceException("Namespace does not exist: %s", namespace);
    }

    Preconditions.checkNotNull(properties, "Invalid properties to remove: null");

    if (properties.isEmpty()) {
      return false;
    }

    return client.removeParameters(toDatasetReference(namespace), properties);
  }

  @Override
  public Map<String, String> loadNamespaceMetadata(Namespace namespace) {
    try {
      return toMetadata(client.load(toDatasetReference(namespace)));
    } catch (IllegalArgumentException e) {
      throw new NoSuchNamespaceException("%s", e.getMessage());
    }
  }

  @Override
  protected boolean isValidIdentifier(TableIdentifier identifier) {
    try {
      validateNamespace(identifier.namespace());
    } catch (IllegalArgumentException e) {
      return false;
    }
    return true;
  }

  @Override
  public String name() {
    return catalogName;
  }

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Verify the dataset exists with bq show <project>:<dataset_id>
2. Check namespace components form a valid BigQuery dataset id (letters, numbers, underscores)
3. Confirm the catalog project id matches where the dataset lives
4. Catch NoSuchNamespaceException around loadNamespaceMetadata for missing-namespace handling

Example fix

// before
Map<String,String> meta = catalog.loadNamespaceMetadata(ns);
// after
try {
  Map<String,String> meta = catalog.loadNamespaceMetadata(ns);
} catch (NoSuchNamespaceException e) {
  // namespace no longer backed by a BigQuery dataset
}

if (!catalog.namespaceExists(namespace)) { /* skip load */ }

try { catalog.loadNamespaceMetadata(ns); } catch (NoSuchNamespaceException e) { /* dataset backing namespace missing */ }

When it happens

Trigger: Calling catalog.loadNamespaceMetadata(namespace) where the BigQuery dataset is missing or the client's load path rejects the dataset reference (invalid dataset id, dataset not found surfaced as IllegalArgumentException).

Common situations: Dataset deleted by a scheduled cleanup job while Iceberg metadata still references it, illegal characters in namespace producing an invalid dataset id, cross-project references the client does not resolve.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• fail to find Glue database for namespace %s, error message:
• Namespace does not exist: %s
• Namespace already exists: %s
• %s is not empty: %s
• Cannot create namespace " + namespace + ": metadata is not s

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