apache/iceberg · error · UnsupportedOperationException

Namespaces are not supported by catalog:

Error message

Namespaces are not supported by catalog:

What it means

FlinkCatalog throws UnsupportedOperationException with message 'Namespaces are not supported by catalog: <name>' when createDatabase is invoked but the underlying Iceberg catalog does not implement NamespaceCatalog (asNamespaceCatalog == null). Such catalogs only expose the single default database, so creating databases is impossible.

Source

Thrown at flink/v2.2/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. Switch to an Iceberg catalog implementing NamespaceCatalog (HiveCatalog, HadoopCatalog, RESTCatalog, JdbcCatalog, NessieCatalog)
  2. Use the single default database the non-namespace catalog exposes instead of creating new databases
  3. Implement NamespaceCatalog in your custom catalog if you need multi-database support

Example fix

// before
CREATE DATABASE db1; // UnsupportedOperationException
// after
// load a namespace-capable catalog
Catalog iceberg = CatalogLoader.loadCatalog("hadoop", warehousePath, props, hadoopConf);
CREATE DATABASE db1;
Defensive patterns

Strategy: fallback

Validate before calling

boolean supportsNamespaces = icebergCatalog instanceof NamespaceCatalog; if (!supportsNamespaces) { /* restrict to default db */ }

Type guard

NamespaceCatalog asNs = (icebergCatalog instanceof NamespaceCatalog ns) ? ns : null;

Try / catch

try { catalog.createDatabase(name, props, false); } catch (UnsupportedOperationException e) { LOG.warn("Catalog {} has no namespace support; using default db", catalog.getName()); }

Prevention

When it happens

Trigger: CREATE DATABASE x (or catalog.createDatabase) against a FlinkCatalog wrapping a non-namespace Iceberg catalog (asNamespaceCatalog == null) — this branch always throws regardless of the name.

Common situations: Configuring the Flink Iceberg catalog with a custom Catalog implementation lacking namespace support; users then attempt to organize tables into databases.

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

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