apache/iceberg · error · CatalogException

Database properties should not contain key: 'comment'.

Error message

Database properties should not contain key: 'comment'.

What it means

FlinkCatalog.mergeComment validates that the database properties map does not already contain the reserved key 'comment', since Flink passes the database comment separately. A 'comment' entry inside metadata would collide with the comment argument, so creation aborts with CatalogException.

Source

Thrown at flink/v1.20/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 WITH/properties clause and pass it only via COMMENT 'x' (or vice versa).
2. Strip 'comment' from the properties map before calling createDatabase programmatically.
3. Use a different property key (e.g. 'comment' is reserved; choose 'notes' or a custom key).

Example fix

// before
CREATE DATABASE db WITH ('comment' = 'x');
// after
CREATE DATABASE db COMMENT 'x';

Map<String, String> safe = new HashMap<>(props);
safe.remove("comment");
flinkCatalog.createDatabase(name, safe, ignoreIfExists);

try {
  flinkCatalog.createDatabase(name, props, false);
} catch (CatalogException e) {
  // strip 'comment' key and retry, or surface a clear DDL fix
}

When it happens

Trigger: createDatabase (or newProperties) is called with database metadata containing key 'comment' — e.g. Flink SQL CREATE DATABASE ... WITH ('comment'='x') plus a COMMENT clause, or programmatic creation passing a properties map containing 'comment'.

Common situations: Specifying the comment both as a Flink option and as a database property; ORM/tooling that serializes comments into the properties map; migrating DDL from another engine that put comments in properties.

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

• Database properties should not contain key: 'comment'.
• Database properties should not contain key: 'comment'.
• Illegal table name:
• Namespaces are not supported by catalog:
• Can not alter the default database when the iceberg catalog

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