apache/iceberg · error · CatalogException

Database properties should not contain key: 'comment'.

Error message

Database properties should not contain key: 'comment'.

What it means

mergeComment rejects database properties that already contain the reserved key 'comment', because Flink passes the database comment both as a property and as an explicit comment parameter; keeping it in the property map would create a conflict. The library throws CatalogException to force the caller to remove 'comment' from metadata before merging the explicit comment.

Source

Thrown at flink/v2.1/flink/src/main/java/org/apache/iceberg/flink/FlinkCatalog.java:240

      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;
  }

  @Override
  public void dropDatabase(String name, boolean ignoreIfNotExists, boolean cascade)
      throws DatabaseNotExistException, DatabaseNotEmptyException, CatalogException {
    if (asNamespaceCatalog != null) {
      try {
        boolean success = asNamespaceCatalog.dropNamespace(appendLevel(baseNamespace, name));
        if (!success && !ignoreIfNotExists) {
          throw new DatabaseNotExistException(getName(), name);
        }
      } catch (NoSuchNamespaceException e) {

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Remove the 'comment' key from the properties map before calling createDatabase
2. Pass the comment via the dedicated comment parameter instead of as a property
3. Filter reserved keys generically before submitting database metadata

Example fix

// before
catalog.createDatabase("db", Map.of("comment", "hello"), null);
// after
Map<String, String> props = new HashMap<>(metadata);
props.remove("comment");
catalog.createDatabase("db", props, "hello");

if (metadata.containsKey("comment")) {
  throw new IllegalArgumentException("Remove reserved 'comment' key before createDatabase");
}

null

try { catalog.createDatabase(name, metadata, comment); } catch (CatalogException e) { /* remove 'comment' key and retry once */ }

When it happens

Trigger: Calling createDatabase(name, metadata, comment) or newProperties with a properties map that includes key "comment", typically when copying properties from an existing Hive/Spark database.

Common situations: Migrating databases from Hive Metastore where 'comment' is stored as a property; generic tooling that passes through arbitrary database metadata without filtering reserved keys.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• Source table %s contains one/all of the reserved property ke
• Cannot create the table with 'connector'='iceberg' table pro
• Invalid precision: ${precision}
• Invalid precision: ${precision}
• Namespaces are not supported by catalog:

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