apache/iceberg · error · UnsupportedOperationException

Namespaces are not supported by catalog:

Error message

Namespaces are not supported by catalog: 

What it means

FlinkCatalog.createDatabase throws UnsupportedOperationException when the underlying Iceberg catalog is not a NamespaceCatalog (e.g. a plain TableCatalog like Hadoop/Hive in table-only mode) — such catalogs have no database concept, so namespace creation cannot be forwarded.

Source

Thrown at flink/v1.20/flink/src/main/java/org/apache/iceberg/flink/FlinkCatalog.java:232

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

  @Override
  public void dropDatabase(String name, boolean ignoreIfNotExists, boolean cascade)

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Configure the Flink Iceberg catalog with a namespace-capable implementation (HadoopCatalog, HiveCatalog, REST catalog with namespaces).
2. Don't create databases — use only the default database (tables go directly under the catalog).
3. Check catalog type in code: only call createDatabase when the wrapped catalog implements NamespaceCatalog.
4. Set catalog properties so the Iceberg catalog resolves to a NamespaceCatalog implementation.

Example fix

// before
CREATE DATABASE iceberg_catalog.my_db;
// after: only with a namespace-capable catalog, or use default db
CREATE TABLE iceberg_catalog.my_db.t1 (...);

if (!(flinkCatalog.getWrappedCatalog() instanceof NamespaceCatalog)) {
  throw new UnsupportedOperationException("CREATE DATABASE unsupported for this Iceberg catalog");
}

boolean supportsNamespaces(FlinkCatalog c) { return c.asNamespaceCatalog() != null; }

try {
  flinkCatalog.createDatabase(name, props, ignoreIfExists);
} catch (UnsupportedOperationException e) {
  // fall back to default database or reconfigure catalog
}

When it happens

Trigger: CREATE DATABASE on an Iceberg Flink catalog instance backed by a catalog that does not implement NamespaceCatalog (asNamespaceCatalog == null), e.g. the default 'iceberg' catalog without namespace support configured.

Common situations: Running CREATE DATABASE my_db against an Iceberg catalog wired to a table-only backend; switching the catalog implementation (REST/Hadoop) and forgetting that only NamespaceCatalog implementations accept databases; using the default database-only catalog in Flink SQL.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Can not alter the default database when the iceberg catalog
• Namespaces are not supported by catalog:
• Illegal table name:
• Database properties should not contain key: 'comment'.
• Source table %s contains one/all of the reserved property ke

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