apache/iceberg · error · AlreadyExistsException

Namespace already exists: %s

Error message

Namespace already exists: %s

What it means

createNamespace throws AlreadyExistsException when the namespace already exists in the JDBC catalog. The check runs before inserting the namespace metadata row. Namespaces are stored as rows in the catalog tables, so duplicates violate the uniqueness contract of the Catalog API.

Source

Thrown at core/src/main/java/org/apache/iceberg/jdbc/JdbcCatalog.java:416

          "Rename operation affected {} rows: the catalog table's primary key assumption has been violated",
          updatedRecords);
    }
  }

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

  @Override
  public void setConf(Object conf) {
    this.conf = conf;
  }

  @Override
  public void createNamespace(Namespace namespace, Map<String, String> metadata) {
    if (namespaceExists(namespace)) {
      throw new AlreadyExistsException("Namespace already exists: %s", namespace);
    }

    Map<String, String> createMetadata;
    if (metadata == null || metadata.isEmpty()) {
      createMetadata = ImmutableMap.of(NAMESPACE_EXISTS_PROPERTY, "true");
    } else {
      createMetadata =
          ImmutableMap.<String, String>builder()
              .putAll(metadata)
              .put(NAMESPACE_EXISTS_PROPERTY, "true")
              .buildOrThrow();
    }

    insertProperties(namespace, createMetadata);
  }

  @Override
  public List<Namespace> listNamespaces() {

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Check catalog.namespaceExists(ns) before creating, or skip on AlreadyExistsException
2. Use namespaceExists as an idempotency guard in setup scripts
3. If the existing namespace is unwanted, drop it first (it must be empty) then recreate

Example fix

// before
catalog.createNamespace(ns);
// after
if (!catalog.namespaceExists(ns)) {
  catalog.createNamespace(ns);
}

When it happens

Trigger: Calling catalog.createNamespace(namespace, metadata) where catalog.namespaceExists(namespace) returns true.

Common situations: Initialization scripts run twice; concurrent creation of the same namespace by multiple clients; re-running setup after a partial bootstrap that already created the namespace.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

• Cannot create namespace %s because it already exists in Glue
• Namespace already exists: %s
• Namespace already exists: %s
• Cannot create namespace %s. Namespace already exists
• Cannot rename %s to %s. View already exists

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