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

alterDatabase on a non-NamespaceCatalog-backed Flink Iceberg catalog rejects altering the default database: since no real namespaces exist, the default database is virtual and its properties can never be persisted, so any alter fails with this CatalogException.

Source

Thrown at flink/v1.20/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

Switch to a namespace-capable Iceberg catalog implementation (HiveCatalog/HadoopCatalog/REST) if you need database properties.
Don't alter the default database — create tables directly and put properties on tables instead.
Guard code: skip alterDatabase when name equals the default database and the catalog lacks namespace support, to fail gracefully.
Store the intended settings in Flink session/dynamic table options rather than database properties.

Example fix

// before
ALTER DATABASE iceberg_catalog.`default` SET ('write.format.default'='orc');
// after: set on the table instead
ALTER TABLE iceberg_catalog.db.t1 SET ('write.format.default'='orc');

Defensive patterns

Strategy: validation

Validate before calling

if ("default".equals(dbName) && !(catalog instanceof NamespaceCatalog)) {
  skipAlter(); // or fail with actionable message
}

Type guard

boolean canAlterDatabase(String name) {
  return flinkCatalog.asNamespaceCatalog() != null || !flinkCatalog.getDefaultDatabase().equals(name);
}

Try / catch

try {
  flinkCatalog.alterDatabase(name, changes, ignoreIfNotExists);
} catch (CatalogException e) {
  // apply properties at table level instead
}

Prevention

Don't ALTER DATABASE the default database on namespace-less catalogs.
Put settings on tables rather than the virtual default database.
Choose a namespace-capable catalog implementation when database properties are required.

When it happens

Trigger: Calling FlinkCatalog.alterDatabase (ALTER DATABASE ... SET PROPERTIES) where the underlying Iceberg catalog is not a NamespaceCatalog AND the target database name equals getDefaultDatabase() (usually 'default').

Common situations: Running ALTER DATABASE default SET ('k'='v') in Flink SQL against a table-only Iceberg catalog; application code adjusting default-namespace properties expecting Hadoop/Hive-like behavior.

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/4a96573edd8027d2. Report an issue: GitHub.