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.

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
• Can not alter the default database when the iceberg catalog…
• Can not alter the default database when the iceberg catalog…
• Cannot apply unknown namespace change

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

Appendix: 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)