apache/iceberg · error · AlreadyExistsException

namespace %s(%s) has already existed

Error message

namespace %s(%s) has already existed

What it means

EcsCatalog.createNamespace throws AlreadyExistsException when putNewProperties cannot create the namespace marker object because an object already exists at the namespace URI. Namespaces in ECS are represented by a marker object, so its existence means the namespace was already created.

Source

Thrown at dell/src/main/java/org/apache/iceberg/dell/ecs/EcsCatalog.java:269

    }

    Properties properties = loadProperties(fromURI);
    EcsURI toURI = tableURI(to);

    if (!putNewProperties(toURI, properties.content())) {
      throw new AlreadyExistsException(
          "Cannot rename %s because destination table %s exists", from, to);
    }

    client.deleteObject(fromURI.bucket(), fromURI.name());
    LOG.info("Rename table {} to {}", from, to);
  }

  @Override
  public void createNamespace(Namespace namespace, Map<String, String> properties) {
    EcsURI namespaceObject = namespaceURI(namespace);
    if (!putNewProperties(namespaceObject, properties)) {
      throw new AlreadyExistsException(
          "namespace %s(%s) has already existed", namespace, namespaceObject);
    }
  }

  private EcsURI namespaceURI(Namespace namespace) {
    return new EcsURI(String.format("%s%s", namespacePrefix(namespace), NAMESPACE_OBJECT_SUFFIX));
  }

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

    String marker = null;
    List<Namespace> results = Lists.newArrayList();
    // Add the end slash when delimiter listing
    EcsURI prefix = new EcsURI(String.format("%s/", namespacePrefix(namespace)));

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Check catalog.namespaceExists(namespace) before creating and skip if present.
  2. Catch AlreadyExistsException and treat it as success in idempotent provisioning code.
  3. If the marker is a stale leftover, delete the leftover object (e.g. via dropNamespace cleanup) and retry.

Example fix

// before
catalog.createNamespace(Namespace.of("sales"), props);
// after
if (!catalog.namespaceExists(Namespace.of("sales"))) {
  catalog.createNamespace(Namespace.of("sales"), props);
}
Defensive patterns

Strategy: validation

Validate before calling

Namespace ns = Namespace.of("sales");
if (!catalog.namespaceExists(ns)) { catalog.createNamespace(ns); }

Try / catch

try {
  catalog.createNamespace(ns, props);
} catch (AlreadyExistsException e) {
  LOG.info("Namespace {} already exists, continuing", ns);
}

Prevention

When it happens

Trigger: Calling catalog.createNamespace(namespace, properties) when the namespace marker object already exists — either created previously by this catalog or an object occupying the same key (e.g. a leftover marker after an incomplete drop).

Common situations: Idempotent setup scripts that call createNamespace on every run without checking existence; leftover NAMESPACE_OBJECT_SUFFIX marker from a failed drop; two processes creating the same namespace concurrently.

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/7ac540cb40994231. Report an issue: GitHub.