{"record":{"id":"7597b209dd70e1d6","repo":"apache/beam","slug":"attempting-to-use-catalog-s-with-unexpected-calcite-schema","errorCode":null,"errorMessage":"Attempting to 'USE CATALOG' %s' with unexpected Calcite Schema of type %s","messagePattern":"Attempting to 'USE CATALOG' (.+?)' with unexpected Calcite Schema of type (.+?)","errorType":"validation","errorClass":"SqlUtil.newContextException","httpStatus":null,"severity":"error","filePath":"sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/parser/SqlUseCatalog.java","lineNumber":64,"sourceCode":"  }\n\n  @Override\n  public SqlOperator getOperator() {\n    return OPERATOR;\n  }\n\n  @Override\n  public List<SqlNode> getOperandList() {\n    return Collections.singletonList(catalogName);\n  }\n\n  @Override\n  public void execute(CalcitePrepare.Context context) {\n    final Pair<CalciteSchema, String> pair = SqlDdlNodes.schema(context, true, catalogName);\n    Schema schema = pair.left.schema;\n\n    if (!(schema instanceof CatalogManagerSchema)) {\n      throw SqlUtil.newContextException(\n          catalogName.getParserPosition(),\n          RESOURCE.internal(\n              \"Attempting to 'USE CATALOG' \"\n                  + catalogName\n                  + \"' with unexpected Calcite Schema of type \"\n                  + schema.getClass()));\n    }\n\n    ((CatalogManagerSchema) schema).useCatalog(catalogName);\n  }\n}\n","sourceCodeStart":46,"sourceCodeEnd":76,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/parser/SqlUseCatalog.java#L46-L76","documentation":"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.","triggerScenarios":"Executing a `USE CATALOG <name>` statement where SqlDdlNodes.schema(context, true, catalogName) resolves to a CalciteSchema whose .schema is not a CatalogManagerSchema instance.","commonSituations":"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.","solutions":["Ensure the catalog referenced by USE CATALOG is registered through Beam's catalog manager so the resolved schema is a CatalogManagerSchema.","Verify the catalog name in the statement matches a catalog actually managed by Beam (check for typos).","If using custom Calcite schema setup, wrap or adapt it with Beam's CatalogManagerSchema before executing DDL/DML statements.","Avoid USE CATALOG entirely when running against a single default catalog."],"exampleFix":"// before\nconnection.createStatement().executeSql(\"USE CATALOG `mycatalog`\"); // mycatalog is a raw Calcite schema\n// after\nconnection.createStatement().executeSql(\"USE CATALOG `beam_catalog`\"); // registered via BeamCatalogManager","handlingStrategy":"validation","validationCode":"// Ensure the catalog is registered with Beam's catalog manager before USE CATALOG\nSchema catalog = catalogManager.getSchema(catalogName);\nif (!(catalog instanceof CatalogManagerSchema)) {\n  throw new IllegalStateException(catalogName + \" is not managed by Beam's CatalogManager\");\n}","typeGuard":"if (!(schema instanceof CatalogManagerSchema)) { /* fall back / fail fast */ }","tryCatchPattern":null,"preventionTips":["Only switch catalogs registered through Beam's catalog manager.","Keep catalog names in a constants/config file to avoid typos.","Prefer fully qualified table names over catalog switching in portable pipelines."],"tags":["sql","calcite","catalog","beam"],"backgroundTag":"incompatible-source-type","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"}