apache/beam · error · SqlUtil.newContextException

Attempting to 'USE CATALOG

Error message

Attempting to 'USE CATALOG' %s' with unexpected Calcite Schema of type %s

What it means

Beam SQL's `USE CATALOG` parser node resolves the named catalog via Calcite and requires the resolved schema to be a CatalogManagerSchema, which is the only type that supports catalog switching. If Calcite resolved the name to some other Schema implementation, this internal IllegalStateException-style context exception is thrown. It indicates the schema setup is inconsistent with Beam's catalog management expectations.

Solutions

1. Ensure the catalog referenced by USE CATALOG is registered through Beam's catalog manager so the resolved schema is a CatalogManagerSchema.
2. Verify the catalog name in the statement matches a catalog actually managed by Beam (check for typos).
3. If using custom Calcite schema setup, wrap or adapt it with Beam's CatalogManagerSchema before executing DDL/DML statements.
4. Avoid USE CATALOG entirely when running against a single default catalog.

Example fix

// before
connection.createStatement().executeSql("USE CATALOG `mycatalog`"); // mycatalog is a raw Calcite schema
// after
connection.createStatement().executeSql("USE CATALOG `beam_catalog`"); // registered via BeamCatalogManager

// Ensure the catalog is registered with Beam's catalog manager before USE CATALOG
Schema catalog = catalogManager.getSchema(catalogName);
if (!(catalog instanceof CatalogManagerSchema)) {
  throw new IllegalStateException(catalogName + " is not managed by Beam's CatalogManager");
}

if (!(schema instanceof CatalogManagerSchema)) { /* fall back / fail fast */ }

When it happens

Trigger: Executing a `USE CATALOG <name>` statement where SqlDdlNodes.schema(context, true, catalogName) resolves to a CalciteSchema whose .schema is not a CatalogManagerSchema instance.

Common situations: Registering a plain Calcite root/sub schema without wrapping it in Beam's CatalogManagerSchema; using a custom SchemaPlus provider; running SQL against a non-Beam catalog configuration.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• Attempting to create database
• Attempting to alter catalog
• Attempting to create catalog
• Attempting to drop a catalog
• Cannot drop catalog: ' ' not found.

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

Appendix: source

Thrown at sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/parser/SqlUseCatalog.java:64

  }

  @Override
  public SqlOperator getOperator() {
    return OPERATOR;
  }

  @Override
  public List<SqlNode> getOperandList() {
    return Collections.singletonList(catalogName);
  }

  @Override
  public void execute(CalcitePrepare.Context context) {
    final Pair<CalciteSchema, String> pair = SqlDdlNodes.schema(context, true, catalogName);
    Schema schema = pair.left.schema;

    if (!(schema instanceof CatalogManagerSchema)) {
      throw SqlUtil.newContextException(
          catalogName.getParserPosition(),
          RESOURCE.internal(
              "Attempting to 'USE CATALOG' "
                  + catalogName
                  + "' with unexpected Calcite Schema of type "
                  + schema.getClass()));
    }

    ((CatalogManagerSchema) schema).useCatalog(catalogName);
  }
}

View on GitHub (pinned to 12126d8942)