What causes "Namespace already exists: ${namespace}" in apache/iceberg?

Use 'CREATE NAMESPACE IF NOT EXISTS ' in SQL

apache/iceberg · error · NamespaceAlreadyExistsException

Namespace already exists: ${namespace}

Error message

Namespace already exists: ${namespace}

What it means

Thrown by SparkCatalog.createNamespace when the underlying Iceberg catalog raises AlreadyExistsException because a namespace with the same name already exists; Spark translates this into NamespaceAlreadyExistsException. Creation is refused so existing namespace metadata is not overwritten.

Source

Thrown at spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java:523

    throw new NoSuchNamespaceException(namespace);
  }

  @Override
  public void createNamespace(String[] namespace, Map<String, String> metadata)
      throws NamespaceAlreadyExistsException {
    if (asNamespaceCatalog != null) {
      try {
        if (asNamespaceCatalog instanceof HadoopCatalog
            && DEFAULT_NS_KEYS.equals(metadata.keySet())) {
          // Hadoop catalog will reject metadata properties, but Spark automatically adds "owner".
          // If only the automatic properties are present, replace metadata with an empty map.
          asNamespaceCatalog.createNamespace(Namespace.of(namespace), ImmutableMap.of());
        } else {
          asNamespaceCatalog.createNamespace(Namespace.of(namespace), metadata);
        }
      } catch (AlreadyExistsException e) {
        throw new NamespaceAlreadyExistsException(namespace);
      }
    } else {
      throw new UnsupportedOperationException(
          "Namespaces are not supported by catalog: " + catalogName);
    }
  }

  @Override
  public void alterNamespace(String[] namespace, NamespaceChange... changes)
      throws NoSuchNamespaceException {
    if (asNamespaceCatalog != null) {
      Map<String, String> updates = Maps.newHashMap();
      Set<String> removals = Sets.newHashSet();
      for (NamespaceChange change : changes) {
        if (change instanceof NamespaceChange.SetProperty) {
          NamespaceChange.SetProperty set = (NamespaceChange.SetProperty) change;
          updates.put(set.property(), set.value());
        } else if (change instanceof NamespaceChange.RemoveProperty) {

View on GitHub (pinned to 86d9c8fc54)

Solutions

Use 'CREATE NAMESPACE IF NOT EXISTS <ns>' in SQL
Check namespaceExists(ns) before creating
Catch NamespaceAlreadyExistsException and treat it as success in idempotent scripts
In Java, call dropNamespace first only when the existing namespace can be safely replaced

Example fix

// before
spark.sql("CREATE NAMESPACE prod.analytics")
// after
spark.sql("CREATE NAMESPACE IF NOT EXISTS prod.analytics")

Defensive patterns

Strategy: try-catch

Validate before calling

if (nsc.namespaceExists(namespace)) {
  log.info("Namespace {} already exists; skipping creation", String.join(".", namespace));
  return;
}

Type guard

boolean needsCreation(SupportsNamespaces catalog, String[] ns) {
  return !catalog.namespaceExists(ns);
}

Try / catch

try {
  nsc.createNamespace(ns, metadata);
} catch (NamespaceAlreadyExistsException e) {
  log.info("Namespace {} already exists; treating as success", String.join(".", ns));
}

Prevention

Use CREATE NAMESPACE IF NOT EXISTS in SQL scripts
Make bootstrap scripts idempotent by catching NamespaceAlreadyExistsException
Check namespaceExists before create
Coordinate namespace creation across concurrent jobs (single provisioner)

When it happens

Trigger: Calling CREATE NAMESPACE <ns> or createNamespace(ns, metadata) for a name that already exists in the catalog, including re-running idempotent-looking setup scripts and races where two jobs create the same namespace concurrently.

Common situations: Idempotent bootstrap scripts without IF NOT EXISTS, re-provisioning after partial failure, multi-tenant setups where another team 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

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