apache/iceberg · error · AlreadyExistsException

Namespace already exists: %s

Error message

Namespace already exists: %s

What it means

NessieIcebergClient.createNamespace checks whether the ContentKey already exists in the configured reference before committing a Put operation. If the key resolves to existing content, it throws AlreadyExistsException 'Namespace already exists: <key>'. This mirrors the Iceberg REST contract for 409 on duplicate namespaces.

Source

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

    try {
      ContentKey key = NessieUtil.toKey(tableIdentifier);
      Content content = withReference(api.getContent().key(key)).get().get(key);
      return content != null ? content.unwrap(IcebergContent.class).orElse(null) : null;
    } catch (NessieNotFoundException e) {
      return null;
    }
  }

  public void createNamespace(Namespace namespace, Map<String, String> metadata) {
    checkNamespaceIsValid(namespace);
    getRef().checkMutable();
    ContentKey key = ContentKey.of(namespace.levels());
    org.projectnessie.model.Namespace content =
        org.projectnessie.model.Namespace.of(key.getElements(), metadata);
    try {
      Content existing = api.getContent().reference(getReference()).key(key).get().get(key);
      if (existing != null) {
        throw namespaceAlreadyExists(key, existing, null);
      }
      try {
        commitRetry("create namespace " + key, Operation.Put.of(key, content));
      } catch (NessieReferenceConflictException e) {
        Optional<Conflict> conflict =
            NessieUtil.extractSingleConflict(
                e,
                EnumSet.of(
                    Conflict.ConflictType.KEY_EXISTS, Conflict.ConflictType.NAMESPACE_ABSENT));
        if (conflict.isPresent()) {
          switch (conflict.get().conflictType()) {
            case KEY_EXISTS:
              Content conflicting = withReference(api.getContent()).key(key).get().get(key);
              throw namespaceAlreadyExists(key, conflicting, e);
            case NAMESPACE_ABSENT:
              throw new NoSuchNamespaceException(
                  e,
                  "Cannot create namespace '%s': parent namespace '%s' does not exist",

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Check existence first with namespaceExists(...) or catch AlreadyExistsException and treat it as success
2. Use a different namespace name or delete the existing namespace first
3. Verify you are pointed at the intended Nessie reference (branch/tag) via the catalog's ref configuration

Example fix

// before
catalog.createNamespace(Namespace.of("db")); // AlreadyExistsException on rerun
// after
if (!catalog.namespaceExists(Namespace.of("db"))) {
  catalog.createNamespace(Namespace.of("db"));
}

if (catalog.namespaceExists(Namespace.of("db"))) { /* skip or reuse */ } else { catalog.createNamespace(Namespace.of("db")); }

try { catalog.createNamespace(ns); } catch (AlreadyExistsException e) { /* treat as success */ }

When it happens

Trigger: Calling createNamespace(Namespace) on a Nessie catalog when an identically named namespace (ContentKey) already exists in the current reference, whether created earlier by you or by another writer.

Common situations: Re-running an idempotency-ignoring setup script; two jobs racing to create the same namespace; recreating a namespace after a branch reset where content still exists.

Related errors

• Cannot update properties on namespace '%s': %s
• Namespace already exists: %s
• namespace %s(%s) has already existed
• Cannot create namespace '%s': parent namespace '%s' does not
• Cannot create namespace '%s': %s

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