{"record":{"id":"b584b9074edb4a7c","repo":"apache/beam","slug":"cannot-use-database-s-not-found","errorCode":null,"errorMessage":"Cannot use database: '%s' not found.","messagePattern":"Cannot use database: '(.+?)' not found\\.","errorType":"validation","errorClass":"SqlUtil.newContextException","httpStatus":null,"severity":"error","filePath":"sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/CatalogSchema.java","lineNumber":126,"sourceCode":"\n    if (alreadyExists) {\n      String message = format(\"Database '%s' already exists.\", name);\n      if (ifNotExists || name.equals(DEFAULT)) {\n        LOG.info(\"Database '{}' already exists.\", name);\n      } else {\n        throw SqlUtil.newContextException(\n            databaseIdentifier.getParserPosition(), RESOURCE.internal(message));\n      }\n    }\n\n    subSchemas.put(name, new BeamCalciteSchema(name, connection, catalog.metaStore(name)));\n  }\n\n  public void useDatabase(SqlIdentifier identifier) {\n    String name = SqlDdlNodes.name(identifier);\n    if (!subSchemas.containsKey(name)) {\n      if (!catalog.databaseExists(name)) {\n        throw SqlUtil.newContextException(\n            identifier.getParserPosition(),\n            RESOURCE.internal(String.format(\"Cannot use database: '%s' not found.\", name)));\n      }\n      subSchemas.put(name, new BeamCalciteSchema(name, connection, catalog.metaStore(name)));\n    }\n\n    if (name.equals(catalog.currentDatabase())) {\n      LOG.info(\"Database '{}' is already in use.\", name);\n      return;\n    }\n\n    catalog.useDatabase(name);\n    LOG.info(\"Switched to database '{}'.\", name);\n  }\n\n  public void dropDatabase(SqlIdentifier identifier, boolean cascade, boolean ifExists) {\n    String name = SqlDdlNodes.name(identifier);\n    try {","sourceCodeStart":108,"sourceCodeEnd":144,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/CatalogSchema.java#L108-L144","documentation":"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.","triggerScenarios":"Executing `USE name` (or equivalent SqlUseStatement path) where `name` was never created and catalog.databaseExists(name) is false.","commonSituations":"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.","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."],"exampleFix":"// before\nUSE analytcis;\n// after\nCREATE DATABASE IF NOT EXISTS analytics;\nUSE analytics;","handlingStrategy":"validation","validationCode":"// Java: confirm existence before USE\nif (!catalog.databaseExists(name)) {\n  stmt.execute(\"CREATE DATABASE IF NOT EXISTS \" + name);\n}\nstmt.execute(\"USE \" + name);","typeGuard":null,"tryCatchPattern":"// Java\ncatch (SQLException e) {\n  if (e.getMessage().contains(\"Cannot use database:\")) {\n    // create it, then retry the USE\n    stmt.execute(\"CREATE DATABASE IF NOT EXISTS \" + name);\n    stmt.execute(\"USE \" + name);\n  } else throw e;\n}","preventionTips":["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."],"tags":["sql","ddl","database","not-found"],"backgroundTag":"resource-not-found","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}