apache/iceberg · error · UnsupportedOperationException

Namespaces are not supported by catalog:

Error message

Namespaces are not supported by catalog: 

What it means

FlinkCatalog throws this UnsupportedOperationException when a namespace operation is attempted against an Iceberg catalog that only supports the single default database (i.e. it does not implement the NamespaceBackend/SupportsNamespaces interface, such as a plain Hadoop-free or Hive-less catalog). createDatabase cannot create a new database, so it fails fast instead of silently misbehaving.

Source

Thrown at flink/v2.1/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. Do not create additional databases; use the default database for all tables
2. Configure a catalog implementation that supports namespaces (e.g. HiveCatalog or JDBC/Hadoop catalog with namespace support)
3. Wrap createDatabase in a capability check: only call it when ((SupportsNamespaces) catalog).supportsNamespaces() is true
4. Catch UnsupportedOperationException/CatalogException and treat as 'database already exists/default only' if the app tolerates it

Example fix

// before
flinkCatalog.createDatabase("analytics", props, false);
// after
if (flinkCatalog instanceof SupportsNamespaces && ((SupportsNamespaces) flinkCatalog).supportsNamespaces()) {
  flinkCatalog.createDatabase("analytics", props, false);
} else {
  // use default database
}

if (!(catalog instanceof SupportsNamespaces ns) || !ns.supportsNamespaces()) {
  throw new IllegalStateException("Catalog does not support namespaces; use the default database");
}

boolean supportsNamespaces = catalog instanceof SupportsNamespaces && ((SupportsNamespaces) catalog).supportsNamespaces();

try { catalog.createDatabase(name, props, false); } catch (UnsupportedOperationException | CatalogException e) { log.warn("Namespaces unsupported, using default database"); }

When it happens

Trigger: Calling catalog.createDatabase(name, ignoreIfExists) when the underlying Iceberg Catalog implementation does not support namespaces (supportsNamespaces() returns false), e.g. using HadoopCatalog-style behavior or a custom catalog without namespace support.

Common situations: Users switching from a Hive or Hadoop catalog that supported databases to a catalog where only the default database exists; SQL scripts with CREATE DATABASE executed against an iceberg catalog configured without namespace support; migration tooling assuming all catalogs support namespaces.

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
• Altering partition keys is not supported yet.
• Namespaces are not supported by catalog:
• 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/9ef4c1144cc8bfdf. Report an issue: GitHub.