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 user-supplied database metadata does not already reserve the 'comment' key, because the comment string is stored separately and merged into properties as 'comment'. Supplying 'comment' inside the metadata map would conflict, so a CatalogException is thrown.

Source

Thrown at flink/v2.3/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 metadata map and pass the description via the dedicated comment parameter.
2. Strip reserved keys before calling: metadata.remove("comment") when copying properties from an existing database.
3. If the comment text came from the map, extract it and pass it as the comment argument instead.
4. Validate input property maps against reserved keys in your own tooling before invoking the catalog.

Example fix

// before
Map<String, String> meta = old.getMetadata(); // contains "comment"
catalog.createDatabase("db", meta, old.getComment(), false);
// after
Map<String, String> meta = new HashMap<>(old.getMetadata());
String comment = meta.remove("comment");
catalog.createDatabase("db", meta, comment != null ? comment : old.getComment(), false);

// strip reserved keys from metadata before createDatabase
static Map<String, String> sanitize(Map<String, String> meta) {
  Map<String, String> copy = new HashMap<>(meta);
  if (copy.containsKey("comment")) {
    throw new IllegalArgumentException("pass 'comment' via the comment parameter, not metadata");
  }
  return copy;
}

try {
  catalog.createDatabase(name, metadata, comment, ignoreIfExists);
} catch (CatalogException e) {
  if (e.getMessage().contains("should not contain key: 'comment'")) {
    Map<String, String> fixed = new HashMap<>(metadata);
    String c = fixed.remove("comment");
    catalog.createDatabase(name, fixed, c != null ? c : comment, ignoreIfExists);
  } else {
    throw e;
  }
}

When it happens

Trigger: Calling createDatabase (or newProperties paths) with a metadata map containing key 'comment' while also (or instead) using the dedicated comment parameter — the map and the explicit comment field collide.

Common situations: Scripts that copy raw namespace properties from an existing database (which include 'comment') back into createDatabase; generic property maps built from config files that happen to define 'comment'.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 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/7e2382d9c73bbd1b. Report an issue: GitHub.