What causes "Cannot use database: '%s' not found." in apache/beam?

Create the database first with CREATE DATABASE before issuing USE.

apache/beam · error · SqlUtil.newContextException

Cannot use database: ' ' not found.

Error message

Cannot use database: '%s' not found.

What it means

Thrown by CatalogSchema.useDatabase when a `USE database` statement targets a database that is neither loaded in the session's subSchemas nor present in the catalog. The catalog's databaseExists(name) returned false, so the switch cannot proceed.

Solutions

Create the database first with CREATE DATABASE before issuing USE.
Check spelling and case of the database name.
Verify the configured catalog is the one containing the database.
List existing databases in the catalog/metaStore to confirm the name.

Example fix

// before
USE analytcis;
// after
CREATE DATABASE IF NOT EXISTS analytics;
USE analytics;

Defensive patterns

Strategy: validation

Validate before calling

// Java: confirm existence before USE
if (!catalog.databaseExists(name)) {
  stmt.execute("CREATE DATABASE IF NOT EXISTS " + name);
}
stmt.execute("USE " + name);

Try / catch

// Java
catch (SQLException e) {
  if (e.getMessage().contains("Cannot use database:")) {
    // create it, then retry the USE
    stmt.execute("CREATE DATABASE IF NOT EXISTS " + name);
    stmt.execute("USE " + name);
  } else throw e;
}

Prevention

Centralize database bootstrap (create-if-missing) before any USE.
Standardize database name casing in scripts.
Verify the connection's catalog configuration matches where databases were created.
List catalog databases in debugging output when names fail to resolve.

When it happens

Trigger: Executing `USE name` (or equivalent SqlUseStatement path) where `name` was never created and catalog.databaseExists(name) is false.

Common situations: Typo in the database name, running USE before the CREATE DATABASE DDL, connecting with a catalog whose databases live in a different metaStore, or case-sensitivity mismatch in the name.

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

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/b584b9074edb4a7c. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/CatalogSchema.java:126

    if (alreadyExists) {
      String message = format("Database '%s' already exists.", name);
      if (ifNotExists || name.equals(DEFAULT)) {
        LOG.info("Database '{}' already exists.", name);
      } else {
        throw SqlUtil.newContextException(
            databaseIdentifier.getParserPosition(), RESOURCE.internal(message));
      }
    }

    subSchemas.put(name, new BeamCalciteSchema(name, connection, catalog.metaStore(name)));
  }

  public void useDatabase(SqlIdentifier identifier) {
    String name = SqlDdlNodes.name(identifier);
    if (!subSchemas.containsKey(name)) {
      if (!catalog.databaseExists(name)) {
        throw SqlUtil.newContextException(
            identifier.getParserPosition(),
            RESOURCE.internal(String.format("Cannot use database: '%s' not found.", name)));
      }
      subSchemas.put(name, new BeamCalciteSchema(name, connection, catalog.metaStore(name)));
    }

    if (name.equals(catalog.currentDatabase())) {
      LOG.info("Database '{}' is already in use.", name);
      return;
    }

    catalog.useDatabase(name);
    LOG.info("Switched to database '{}'.", name);
  }

  public void dropDatabase(SqlIdentifier identifier, boolean cascade, boolean ifExists) {
    String name = SqlDdlNodes.name(identifier);
    try {

View on GitHub (pinned to 12126d8942)