apache/beam · error · SqlUtil.newContextException

Cannot use catalog: ' ' not found.

Error message

Cannot use catalog: '%s' not found.

What it means

Context exception thrown by CatalogManagerSchema.useCatalog when the USE CATALOG statement names a catalog that is not registered in the catalog manager. The SQL parser accepted the identifier, but at resolution time no catalog of that name exists in this session, so the statement is rejected with parser-position context pointing at the identifier.

Solutions

  1. Create the catalog first with CREATE CATALOG IF NOT EXISTS name ...
  2. Verify available catalog names and correct the spelling
  3. Ensure prior DDL statements in the script succeeded before USE CATALOG runs

Example fix

// before
USE CATALOG my_catlog;
// after
CREATE CATALOG IF NOT EXISTS my_catalog TYPE ...;
USE CATALOG my_catalog;
Defensive patterns

Strategy: try-catch

Validate before calling

// ensure the catalog exists before USE
stmt.execute("CREATE CATALOG IF NOT EXISTS " + name + " ...");

Try / catch

try {
    stmt.execute("USE CATALOG " + name);
} catch (Exception e) {
    if (e.getMessage().contains("not found")) { stmt.execute("CREATE CATALOG IF NOT EXISTS " + name + " ..."); }
}

Prevention

When it happens

Trigger: Executing `USE CATALOG name` where catalogManager.getCatalog(name) returns null, typically a typo or a catalog that was never created or was dropped.

Common situations: Typo in catalog name; running scripts against a fresh environment where CREATE CATALOG was not executed; catalog dropped in an earlier statement of the same session.

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

Appendix: source

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

        throw SqlUtil.newContextException(
            catalogIdentifier.getParserPosition(),
            RESOURCE.internal(String.format("Catalog '%s' already exists.", name)));
      } else {
        LOG.info("Catalog '{}' already exists", name);
        return;
      }
    }

    catalogManager.createCatalog(name, type, properties);
    CatalogSchema catalogSchema =
        new CatalogSchema(connection, checkStateNotNull(catalogManager.getCatalog(name)));
    catalogSubSchemas.put(name, catalogSchema);
  }

  public void useCatalog(SqlIdentifier catalogIdentifier) {
    String name = catalogIdentifier.toString();
    if (catalogManager.getCatalog(catalogIdentifier.toString()) == null) {
      throw SqlUtil.newContextException(
          catalogIdentifier.getParserPosition(),
          RESOURCE.internal(String.format("Cannot use catalog: '%s' not found.", name)));
    }

    if (catalogManager.currentCatalog().name().equals(name)) {
      LOG.info("Catalog '{}' is already in use.", name);
      return;
    }

    catalogManager.useCatalog(name);
    LOG.info("Switched to catalog '{}' (type: {})", name, catalogManager.currentCatalog().type());
  }

  public void dropCatalog(SqlIdentifier identifier, boolean ifExists) {
    String name = SqlDdlNodes.name(identifier);
    if (catalogManager.getCatalog(name) == null) {
      if (!ifExists) {
        throw SqlUtil.newContextException(

View on GitHub (pinned to 12126d8942)