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 underlying Iceberg catalog does not support namespaces, alterDatabase cannot operate on any database except reporting 'not exists' — but the default database always exists, so altering it would be meaningless. The library throws CatalogException to make this case explicit rather than silently succeeding.

Source

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

Skip the default database in alter-database automation
Use a namespace-capable catalog (Hive/JDBC) if altering databases is required
Guard with a supportsNamespaces() capability check before calling alterDatabase

Example fix

// before
catalog.alterDatabase(catalog.getDefaultDatabase(), changes, false);
// after
if (!name.equals(catalog.getDefaultDatabase())) {
  catalog.alterDatabase(name, changes, false);
}

Defensive patterns

Strategy: validation

Validate before calling

if (catalog.getDefaultDatabase().equals(name)) {
  return; // skip altering default database
}

Type guard

null

Try / catch

try { catalog.alterDatabase(name, changes, false); } catch (CatalogException e) { log.warn("Skip default database alter: {}", name); }

Prevention

Exclude the default database from automated alter loops
Use a namespace-capable catalog if database alteration is a requirement

When it happens

Trigger: Calling alterDatabase(name, ...) where name equals the default database name (getDefaultDatabase()) on a catalog that does not support namespaces.

Common situations: Flink SQL ALTER DATABASE on the default database of an iceberg catalog without namespace support; automated schema-management jobs iterating all databases including the default one.

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/5f3f0654a11b32d4. Report an issue: GitHub.