apache/beam · error · SqlUtil.newContextException

Catalog ' ' already exists.

Error message

Catalog '%s' already exists.

What it means

Thrown during CREATE CATALOG (or CREATE CATALOG OR REPLACE absent) when a catalog with the given name already exists in the CatalogManager. Beam's SQL shell raises it as a Calcite context exception at the statement's parser position. Use IF NOT EXISTS or OR REPLACE to allow the statement to proceed.

Solutions

  1. Add IF NOT EXISTS: CREATE CATALOG IF NOT EXISTS name ...
  2. Use CREATE OR REPLACE CATALOG name ... to overwrite the existing catalog
  3. Pick a different catalog name, or DROP CATALOG the existing one first

Example fix

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

Strategy: try-catch

Validate before calling

// check before running DDL
// SELECT/inspect existing catalogs; skip CREATE if 'my_catalog' already registered

Try / catch

try {
    stmt.execute("CREATE CATALOG my_catalog ...");
} catch (Exception e) {
    if (e.getMessage().contains("already exists")) { /* skip or replace */ }
}

Prevention

When it happens

Trigger: Executing `CREATE CATALOG name ...` where catalogManager.getCatalog(name) != null, replace=false, and ifNotExists=false.

Common situations: Re-running DDL setup scripts that create catalogs idempotently without IF NOT EXISTS; Beam SQL shell interactive sessions repeating an earlier CREATE CATALOG.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

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

Appendix: source

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

  @VisibleForTesting
  public JdbcConnection connection() {
    return connection;
  }

  public void createCatalog(
      SqlIdentifier catalogIdentifier,
      String type,
      Map<String, String> properties,
      boolean replace,
      boolean ifNotExists) {
    String name = SqlDdlNodes.name(catalogIdentifier);
    if (catalogManager.getCatalog(name) != null) {
      if (replace) {
        LOG.info("Replacing existing catalog '{}'", name);
        catalogManager.dropCatalog(name);
      } else if (!ifNotExists) {
        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(

View on GitHub (pinned to 12126d8942)