apache/iceberg · error · DatabaseAlreadyExistException

DatabaseAlreadyExistException

Error message

DatabaseAlreadyExistException

What it means

FlinkCatalog.createDatabase delegates to the namespace catalog's createNamespace; if Iceberg reports AlreadyExistsException and ignoreIfExists is false, it rethrows as Flink's DatabaseAlreadyExistException. The database with that name (under the configured base namespace) is already present, and the caller asked for strict creation semantics.

Source

Thrown at flink/v2.3/flink/src/main/java/org/apache/iceberg/flink/FlinkCatalog.java:228

    }
  }

  @Override
  public void createDatabase(String name, CatalogDatabase database, boolean ignoreIfExists)
      throws DatabaseAlreadyExistException, CatalogException {
    createDatabase(
        name, mergeComment(database.getProperties(), database.getComment()), ignoreIfExists);
  }

  private void createDatabase(
      String databaseName, Map<String, String> metadata, boolean ignoreIfExists)
      throws DatabaseAlreadyExistException, CatalogException {
    if (asNamespaceCatalog != null) {
      try {
        asNamespaceCatalog.createNamespace(appendLevel(baseNamespace, databaseName), metadata);
      } catch (AlreadyExistsException e) {
        if (!ignoreIfExists) {
          throw new DatabaseAlreadyExistException(getName(), databaseName, e);
        }
      }
    } else {
      throw new UnsupportedOperationException(
          "Namespaces are not supported by catalog: " + getName());
    }
  }

  private Map<String, String> mergeComment(Map<String, String> metadata, String comment) {
    Map<String, String> ret = Maps.newHashMap(metadata);
    if (metadata.containsKey("comment")) {
      throw new CatalogException("Database properties should not contain key: 'comment'.");
    }

    if (!StringUtils.isNullOrWhitespaceOnly(comment)) {
      ret.put("comment", comment);
    }
    return ret;

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Use CREATE DATABASE IF NOT EXISTS in SQL or pass ignoreIfExists=true in createDatabase.
2. Check existence first with databaseExists(name) before creating.
3. If the existing database is stale, drop it explicitly before recreating.
4. Serialize bootstrap steps (job scheduling/locks) if concurrent creation is the cause.

Example fix

-- before
CREATE DATABASE analytics;
-- after
CREATE DATABASE IF NOT EXISTS analytics;

// idempotent creation guard
if (!catalog.databaseExists(name)) {
  catalog.createDatabase(name, metadata);
}

try {
  catalog.createDatabase(name, metadata, false);
} catch (DatabaseAlreadyExistException e) {
  log.info("database {} already exists; continuing", name); // idempotent bootstrap
}

When it happens

Trigger: CREATE DATABASE db (without IF NOT EXISTS) or createDatabase(name, meta, false) where the namespace already exists in the backing store — often from re-running idempotent setup scripts or concurrent jobs creating the same database.

Common situations: Replayed SQL migration scripts against an initialized warehouse; two Flink jobs bootstrapping the same database concurrently; CI environments reusing persistent catalog state.

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

• Can not alter the default database when the iceberg catalog
• DatabaseNotExistException
• Namespace does not exist: %s
• Namespace already exists: %s
• Cannot set namespace properties " + namespace + " : setPrope

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