apache/iceberg · error · AlreadyExistsException

Namespace already exists: %s

Error message

Namespace already exists: %s

What it means

HiveCatalog.createNamespace maps Hive Metastore's AlreadyExistsException to Iceberg's org.apache.iceberg.exceptions.AlreadyExistsException when a database (namespace) with the same name already exists in the Hive Metastore. The catalog aborts creation rather than overwriting the existing database.

Source

Thrown at hive-metastore/src/main/java/org/apache/iceberg/hive/HiveCatalog.java:551

        isValidateNamespace(namespace),
        "Cannot support multi part namespace in Hive Metastore: %s",
        namespace);
    Preconditions.checkArgument(
        meta.get(HMS_DB_OWNER_TYPE) == null || meta.get(HMS_DB_OWNER) != null,
        "Create namespace setting %s without setting %s is not allowed",
        HMS_DB_OWNER_TYPE,
        HMS_DB_OWNER);
    try {
      clients.run(
          client -> {
            client.createDatabase(convertToDatabase(namespace, meta));
            return null;
          });

      LOG.info("Created namespace: {}", namespace);

    } catch (org.apache.hadoop.hive.metastore.api.AlreadyExistsException e) {
      throw new AlreadyExistsException(e, "Namespace already exists: %s", namespace);

    } catch (TException e) {
      throw new RuntimeException(
          "Failed to create namespace " + namespace + " in Hive Metastore", e);

    } catch (InterruptedException e) {
      Thread.currentThread().interrupt();
      throw new RuntimeException(
          "Interrupted in call to createDatabase(name) " + namespace + " in Hive Metastore", e);
    }
  }

  @Override
  public List<Namespace> listNamespaces(Namespace namespace) {
    if (!namespace.isEmpty() && (!isValidateNamespace(namespace) || !namespaceExists(namespace))) {
      throw new NoSuchNamespaceException("Namespace does not exist: %s", namespace);
    }
    if (!namespace.isEmpty()) {

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Check existence first with catalog.namespaceExists(namespace) before calling createNamespace, or catch AlreadyExistsException and treat it as success
2. List existing namespaces via catalog.listNamespaces() to confirm the conflicting name
3. Use a different namespace name if the existing database is not yours to reuse
4. If a race is possible, wrap the call in try/catch for AlreadyExistsException instead of pre-checking

Example fix

// before
catalog.createNamespace(Namespace.of("analytics"));
// after
Namespace ns = Namespace.of("analytics");
if (!catalog.namespaceExists(ns)) {
  catalog.createNamespace(ns);
}

Namespace ns = Namespace.of("analytics");
if (catalog.namespaceExists(ns)) {
  throw new IllegalStateException("Namespace already exists: " + ns);
}

try {
  catalog.createNamespace(ns);
} catch (AlreadyExistsException e) {
  // treat as success or fail fast depending on workflow
}

When it happens

Trigger: Calling catalog.createNamespace(Namespace.of("db")) when a Hive database named 'db' already exists in the metastore.

Common situations: Re-running an initialization script without a create-if-not-exists check; two jobs racing to create the same namespace; migrating catalogs where the namespace was created previously; case-sensitivity mismatches making the developer think the namespace is new.

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 rename %s to %s. Namespace does not exist: %s
• Namespace does not exist: %s
• Namespace already exists: %s
• Cannot set namespace properties " + namespace + " : setPrope
• Cannot remove properties " + namespace + " : removePropertie

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