apache/iceberg · error · CommitFailedException

Table is existing when create table

Error message

Table is existing when create table %s

What it means

CommitFailedException thrown by EcsTableOperations.doCommit when creating a new table (base == null) but a properties object already exists at the table's key, so the atomic putNewProperties failed. The table already exists.

Solutions

1. Use catalog.tableExists to check before creating, or load and reuse the existing table
2. Drop the existing table first if recreation is intended
3. Catch CommitFailedException and treat as AlreadyExists

Example fix

// before
catalog.createTable(tableId, schema);
// after
if (!catalog.tableExists(tableId)) {
  catalog.createTable(tableId, schema);
}

if (catalog.tableExists(tableId)) { table = catalog.loadTable(tableId); } else { catalog.createTable(tableId, schema); }

try { catalog.createTable(tableId, schema); } catch (CommitFailedException e) { table = catalog.loadTable(tableId); }

When it happens

Trigger: Calling createTable for a name that already exists in the ECS catalog; the conditional put (expecting the metadata key absent) failed.

Common situations: Concurrent createTable calls with the same identifier, re-running a create job without dropping, leftover properties object from a failed prior creation.

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 commit: Base metadata location
• Cannot commit changes based on stale table metadata
• Cannot commit because base metadata location ' ' is not…
• Cannot commit because Glue detected concurrent update
• Cannot commit due to unexpected exception

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

Appendix: source

Thrown at dell/src/main/java/org/apache/iceberg/dell/ecs/EcsTableOperations.java:95

    } else {
      EcsCatalog.Properties metadata = catalog.loadProperties(tableObject);
      this.eTag = metadata.eTag();
      metadataLocation = metadata.content().get(ICEBERG_METADATA_LOCATION);
      Preconditions.checkNotNull(
          metadataLocation, "Can't find location from table metadata %s", tableObject);
    }

    refreshFromMetadataLocation(metadataLocation);
  }

  @Override
  protected void doCommit(TableMetadata base, TableMetadata metadata) {
    boolean newTable = base == null;
    String newMetadataLocation = writeNewMetadataIfRequired(newTable, metadata);
    if (base == null) {
      // create a new table, the metadataKey should be absent
      if (!catalog.putNewProperties(tableObject, buildProperties(newMetadataLocation))) {
        throw new CommitFailedException("Table is existing when create table %s", tableName());
      }
    } else {
      String cachedETag = eTag;
      Preconditions.checkNotNull(cachedETag, "E-Tag must be not null when update table");
      // replace to a new version, the E-Tag should be present and matched
      boolean result =
          catalog.updatePropertiesObject(
              tableObject, cachedETag, buildProperties(newMetadataLocation));
      if (!result) {
        throw new CommitFailedException(
            "Replace failed, E-Tag %s mismatch for table %s", cachedETag, tableName());
      }
    }
  }

  /** Build properties for table */
  private Map<String, String> buildProperties(String metadataLocation) {
    return ImmutableMap.of(ICEBERG_METADATA_LOCATION, metadataLocation);

View on GitHub (pinned to 86d9c8fc54)