apache/iceberg · error · NoSuchNamespaceException

Namespace does not exist

Error message

Namespace does not exist: %s

What it means

CatalogHandlers.namespaceExists translates a false catalog.namespaceExists result into a REST NoSuchNamespaceException. It is the standard mapping between the Iceberg catalog interface and REST error responses; receiving it means the namespace was not found in the backing catalog.

Solutions

1. Verify the namespace identifier and its levels
2. List existing namespaces (listNamespaces) to confirm the target exists
3. Create the namespace (createNamespace) before operating on it
4. Confirm you are pointed at the intended catalog/backend

Example fix

// before
exists = client.get("v1/namespaces/" + ns, ...); // 404 if missing
// after
ListNamespacesResponse all = client.get("v1/namespaces", ListNamespacesResponse.class);
if (!all.namespaces().contains(ns)) {
  client.post("v1/namespaces", CreateNamespaceRequest.of(ns));
}

List<Namespace> existing = catalog.listNamespaces(parent);
if (!existing.contains(target)) {
  // create or correct the namespace first
}

try {
  handler.namespaceExists(catalog, ns);
} catch (NoSuchNamespaceException e) {
  catalog.createNamespace(ns);
}

When it happens

Trigger: Calling the REST namespace-existence path for a namespace the underlying SupportsNamespaces catalog does not contain.

Common situations: Typos in namespace names; referencing a namespace after it was dropped; environment mismatches (dev vs prod catalog); wrong catalog routing.

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

• Cannot find plan with id
• Cannot list views for namespace. Namespace does not exist
• Could not find plan ID
• Could not find tasks for plan task
• fail to find Glue database for namespace

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

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/rest/CatalogHandlers.java:345

    return ListNamespacesResponse.builder()
        .addAll(page.first())
        .nextPageToken(page.second())
        .build();
  }

  public static CreateNamespaceResponse createNamespace(
      SupportsNamespaces catalog, CreateNamespaceRequest request) {
    Namespace namespace = request.namespace();
    catalog.createNamespace(namespace, request.properties());
    return CreateNamespaceResponse.builder()
        .withNamespace(namespace)
        .setProperties(catalog.loadNamespaceMetadata(namespace))
        .build();
  }

  public static void namespaceExists(SupportsNamespaces catalog, Namespace namespace) {
    if (!catalog.namespaceExists(namespace)) {
      throw new NoSuchNamespaceException("Namespace does not exist: %s", namespace);
    }
  }

  public static GetNamespaceResponse loadNamespace(
      SupportsNamespaces catalog, Namespace namespace) {
    Map<String, String> properties = catalog.loadNamespaceMetadata(namespace);
    return GetNamespaceResponse.builder()
        .withNamespace(namespace)
        .setProperties(properties)
        .build();
  }

  public static void dropNamespace(SupportsNamespaces catalog, Namespace namespace) {
    boolean dropped = catalog.dropNamespace(namespace);
    if (!dropped) {
      throw new NoSuchNamespaceException("Namespace does not exist: %s", namespace);
    }
  }

View on GitHub (pinned to 86d9c8fc54)