apache/iceberg · error · AlreadyExistsException

Namespace already exists: %s

Error message

Namespace already exists: %s

What it means

HadoopCatalog.createNamespace throws AlreadyExistsException when the target namespace directory already exists under the warehouse location. Since namespaces are directories, existence is checked via isNamespace before mkdirs.

Source

Thrown at core/src/main/java/org/apache/iceberg/hadoop/HadoopCatalog.java:291

  @Override
  public void renameTable(TableIdentifier from, TableIdentifier to) {
    throw new UnsupportedOperationException("Cannot rename Hadoop tables");
  }

  @Override
  public void createNamespace(Namespace namespace, Map<String, String> meta) {
    Preconditions.checkArgument(
        !namespace.isEmpty(), "Cannot create namespace with invalid name: %s", namespace);
    if (!meta.isEmpty()) {
      throw new UnsupportedOperationException(
          "Cannot create namespace " + namespace + ": metadata is not supported");
    }

    Path nsPath = new Path(warehouseLocation, SLASH.join(namespace.levels()));

    if (isNamespace(nsPath)) {
      throw new AlreadyExistsException("Namespace already exists: %s", namespace);
    }

    try {
      fs.mkdirs(nsPath);

    } catch (IOException e) {
      throw new RuntimeIOException(e, "Create namespace failed: %s", namespace);
    }
  }

  @Override
  public List<Namespace> listNamespaces(Namespace namespace) {
    Path nsPath =
        namespace.isEmpty()
            ? new Path(warehouseLocation)
            : new Path(warehouseLocation, SLASH.join(namespace.levels()));
    if (!isNamespace(nsPath)) {
      throw new NoSuchNamespaceException("Namespace does not exist: %s", namespace);

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Check namespaceExists(namespace) before calling createNamespace, or catch AlreadyExistsException and treat it as success for idempotent scripts.
2. Inspect the warehouse location for stale/leftover directories and clean them if orphaned.
3. Coordinate namespace creation across concurrent jobs (single bootstrap step).
4. Verify the namespace path doesn't collide with an existing table directory name.

Example fix

// before
catalog.createNamespace(ns, Collections.emptyMap());

// after: idempotent
if (!catalog.namespaceExists(ns)) {
  catalog.createNamespace(ns, Collections.emptyMap());
}

if (!catalog.namespaceExists(ns)) { catalog.createNamespace(ns, Collections.emptyMap()); }

try { catalog.createNamespace(ns, Collections.emptyMap()); } catch (AlreadyExistsException e) { // treat as success in idempotent bootstrap }

When it happens

Trigger: Calling catalog.createNamespace(namespace, meta) when a directory for the namespace already exists at warehouseLocation/<levels> — e.g. a previous creation, a leftover directory, or an existing table directory colliding with the namespace path.

Common situations: Idempotent setup scripts re-run without existence checks, createIfNotExists logic implemented manually, concurrent jobs racing to create the same namespace, or reusing an old warehouse directory containing stale data.

Related errors

• Cannot create namespace %s: already exists
• Namespace already exists: %s
• Table already exists: %s
• namespace %s(%s) has already existed
• View with same name already exists: %s

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