apache/iceberg · error · DatabaseNotExistException

DatabaseNotExistException

Error message

DatabaseNotExistException

What it means

FlinkCatalog.getDatabase throws Flink's DatabaseNotExistException when the underlying catalog does not support namespaces (asNamespaceCatalog == null) and the requested database is not the configured default database. Flat catalogs only expose a single synthetic default database, so any other name cannot exist.

Source

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

  }

  @Override
  public List<String> listDatabases() throws CatalogException {
    if (asNamespaceCatalog == null) {
      return Collections.singletonList(getDefaultDatabase());
    }

    return asNamespaceCatalog.listNamespaces(baseNamespace).stream()
        .map(n -> n.level(n.levels().length - 1))
        .collect(Collectors.toList());
  }

  @Override
  public CatalogDatabase getDatabase(String databaseName)
      throws DatabaseNotExistException, CatalogException {
    if (asNamespaceCatalog == null) {
      if (!getDefaultDatabase().equals(databaseName)) {
        throw new DatabaseNotExistException(getName(), databaseName);
      } else {
        return new CatalogDatabaseImpl(Maps.newHashMap(), "");
      }
    } else {
      try {
        Map<String, String> metadata =
            Maps.newHashMap(
                asNamespaceCatalog.loadNamespaceMetadata(appendLevel(baseNamespace, databaseName)));
        String comment = metadata.remove("comment");
        return new CatalogDatabaseImpl(metadata, comment);
      } catch (NoSuchNamespaceException e) {
        throw new DatabaseNotExistException(getName(), databaseName, e);
      }
    }
  }

  @Override
  public boolean databaseExists(String databaseName) throws CatalogException {

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Use the catalog's default database name instead of an explicit namespace, or prefix nothing in SQL.
2. Reconfigure the catalog to a namespace-capable implementation (e.g. HadoopCatalog/JdbcCatalog/NamespaceCatalog-backed) if real databases are needed.
3. Check the 'catalog.type'/base-namespace configuration to confirm whether namespace support is expected.
4. Catch DatabaseNotExistException and fall back to the default database for legacy queries.

Example fix

// before
CatalogDatabase db = catalog.getDatabase("analytics"); // flat catalog
// after
CatalogDatabase db = catalog.getDatabase(catalog.getDefaultDatabase());

// verify the catalog supports namespaces before addressing non-default databases
boolean namespaced = catalog.listDatabases().size() > 1 || !catalog.getDefaultDatabase().equals(databaseName);

try {
  CatalogDatabase db = catalog.getDatabase(name);
} catch (DatabaseNotExistException e) {
  // fall back to default database for flat catalogs
  db = catalog.getDatabase(catalog.getDefaultDatabase());
}

When it happens

Trigger: Calling getDatabase (directly or via databaseExists/listTables paths) with a non-default database name on a catalog impl that lacks namespace support, e.g. type of catalog configured without nested-namespace capability.

Common situations: Flink SQL 'USE db' or 'SHOW CREATE TABLE db.tbl' against an Iceberg catalog deployed in flat mode; migration from an Hadoop/Hive catalog (namespaced) to a flat catalog while old SQL references remain.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Can not alter the default database when the iceberg catalog
• DatabaseAlreadyExistException
• Namespace does not exist: %s
• Namespace already exists: %s
• Cannot set namespace properties " + namespace + " : setPrope

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