apache/iceberg · error · CatalogException

Can not alter the default database when the iceberg catalog

Error message

Can not alter the default database when the iceberg catalog doesn't support namespaces.

What it means

When the wrapped Iceberg catalog does not support namespaces (asNamespaceCatalog == null), FlinkCatalog.alterDatabase rejects any attempt to alter the default database with a plain CatalogException, because database metadata cannot exist without namespace support. This is a hard guard, not influenced by ignoreIfNotExists.

Source

Thrown at flink/v2.3/flink/src/main/java/org/apache/iceberg/flink/FlinkCatalog.java:312

          }
        }

        if (!updates.isEmpty()) {
          asNamespaceCatalog.setProperties(namespace, updates);
        }

        if (!removals.isEmpty()) {
          asNamespaceCatalog.removeProperties(namespace, removals);
        }

      } catch (NoSuchNamespaceException e) {
        if (!ignoreIfNotExists) {
          throw new DatabaseNotExistException(getName(), name, e);
        }
      }
    } else {
      if (getDefaultDatabase().equals(name)) {
        throw new CatalogException(
            "Can not alter the default database when the iceberg catalog doesn't support namespaces.");
      }
      if (!ignoreIfNotExists) {
        throw new DatabaseNotExistException(getName(), name);
      }
    }
  }

  @Override
  public List<String> listTables(String databaseName)
      throws DatabaseNotExistException, CatalogException {
    try {
      return icebergCatalog.listTables(appendLevel(baseNamespace, databaseName)).stream()
          .map(TableIdentifier::name)
          .collect(Collectors.toList());
    } catch (NoSuchNamespaceException e) {
      throw new DatabaseNotExistException(getName(), databaseName, e);
    }

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Skip altering the default database in scripts targeting catalogs without namespace support
2. Switch to a namespace-capable catalog backend (Hadoop/Hive/JDBC/REST) if database-level properties are required
3. Wrap the alter call so it filters out the default database before invoking
4. Store the desired metadata elsewhere (e.g. table-level properties) if the backend cannot hold DB properties

Example fix

// before
catalog.alterDatabase(catalog.getDefaultDatabase(), db, false); // CatalogException
// after
if (!catalog.getDefaultDatabase().equals(dbName)) {
  catalog.alterDatabase(dbName, db, false);
}

boolean isDefault = dbName.equals(defaultDatabase); // skip alter when true

static boolean isAlterable(Catalog catalog, String dbName) {
  return !dbName.equals(catalog.getDefaultDatabase());
}

try {
  catalog.alterDatabase(name, newDb, false);
} catch (CatalogException e) {
  LOG.warn("Default database cannot be altered on this catalog: {}", e.getMessage());
}

When it happens

Trigger: alterDatabase(getDefaultDatabase(), newDatabase, ignoreIfNotExists) on a catalog without namespace support — the guard getDefaultDatabase().equals(name) fires before anything else.

Common situations: Trying to set properties on the 'default' database of a limited Iceberg catalog backend; porting code written for Hive/Hadoop catalogs to a backend that only exposes the default DB; automated DDL scripts that alter all databases unconditionally.

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

• DatabaseNotEmptyException
• TableNotExistException
• FunctionNotExistException
• Illegal table name:
• Namespaces are not supported by catalog:

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