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

Flink's alterDatabase was called on an Iceberg catalog whose underlying icebergCatalog does not implement NamespaceCatalog (no namespace support), and the target name is the default database. Since there is no namespace backend to alter, Iceberg refuses to silently alter the built-in default database and throws a CatalogException. This guards against operations that appear to succeed but have no real backing metadata.

Source

Thrown at flink/v2.2/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

Do not run ALTER DATABASE against the default database in an Iceberg catalog without namespace support; remove the statement or apply the properties at the table level.
Configure the underlying Iceberg catalog to a namespace-supporting implementation (e.g. HiveCatalog, JdbcCatalog, REST catalog) so alterDatabase takes the NamespaceCatalog path.
If the alter is best-effort, guard the SQL: only issue ALTER DATABASE when the catalog supports namespaces and the database is not the default.

Example fix

// before
ALTER DATABASE `default` SET ('table.warehouse'='/tmp/wh');

// after
-- remove the ALTER DATABASE; set properties per table instead
CREATE TABLE t (...) WITH ('table.warehouse'='/tmp/wh');

Defensive patterns

Strategy: validation

Validate before calling

if ("default".equals(databaseName) && !namespaceCatalogSupportsNamespaces(catalog)) {
  throw new SkipAlterException("ALTER DATABASE on default db is unsupported");
}

Type guard

boolean supportsNamespaces = icebergCatalog instanceof org.apache.iceberg.catalog.NamespaceCatalog;

Prevention

Never issue ALTER DATABASE on the 'default' database in an Iceberg catalog.
Check that the underlying catalog implements NamespaceCatalog before database-level operations.
Prefer table-level properties over database-level properties in Iceberg.

When it happens

Trigger: Calling FlinkCatalog.alterDatabase(ObjectPath/name, CatalogDatabase, ignoreIfNotExists) where the wrapped icebergCatalog is not a NamespaceCatalog and the database name equals getDefaultDatabase() (typically 'default'). The check at FlinkCatalog.java:311 fires before the DatabaseNotExistException fallback.

Common situations: Submitting Flink SQL like ALTER DATABASE `default` SET (...) while using an Iceberg catalog backed by a catalog type without namespace support (e.g. some Hive/REST/JDBC configurations where the catalog is loaded as a plain Catalog, not a NamespaceCatalog); job SQL migration from a Hive catalog to an Iceberg catalog.

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/00015964ec6f1e01. Report an issue: GitHub.