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 metadata maps that already contain the reserved key 'comment' with CatalogException "Database properties should not contain key: 'comment'." The comment is stored separately by Flink, so passing it inside properties would create a conflict that Iceberg/Flink resolves by refusing the operation.

Source

Thrown at flink/v2.2/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/alterDatabase
2. Pass the comment through the dedicated mechanism (Flink DDL COMMENT clause / CatalogDatabase comment) instead of as a property
3. Strip reserved keys when copying metadata programmatically

Example fix

// before
Map<String, String> props = Maps.newHashMap(sourceProps); // contains 'comment'
catalog.createDatabase("db", props);
// after
Map<String, String> props = Maps.newHashMap(sourceProps);
props.remove("comment");
catalog.createDatabase("db", props);

if (props.containsKey("comment")) { throw new IllegalArgumentException("Remove 'comment' from properties; pass it as the database comment"); }

try { catalog.alterDatabase(name, newDatabase, false); } catch (CatalogException e) { if (e.getMessage().contains("comment")) { /* strip key and retry */ } }

When it happens

Trigger: createDatabase(name, metadata) or alterDatabase (via newProperties/mergeComment) where the user-supplied properties map contains key 'comment', which Flink treats as the database comment field rather than an ordinary property.

Common situations: Copying namespace metadata (e.g. from another catalog's output) without stripping 'comment'; hand-written DDL like CREATE DATABASE x WITH ('comment'='...') where the connector expects comment as a separate option.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Database properties should not contain key: 'comment'.
• Database properties should not contain key: 'comment'.
• Invalid identifier: %s
• Illegal table name:
• Namespaces are not supported by catalog:

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