{"record":{"id":"79350b91aac42261","repo":"apache/beam","slug":"beam-jdbc-connection-has-not-been-initialized","errorCode":null,"errorMessage":"Beam JDBC connection has not been initialized","messagePattern":"Beam JDBC connection has not been initialized","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/BeamCalciteSchemaFactory.java","lineNumber":228,"sourceCode":"\n    @Override\n    public Expression getExpression(@Nullable SchemaPlus parentSchema, String name) {\n      return illegal();\n    }\n\n    @Override\n    public boolean isMutable() {\n      return illegal();\n    }\n\n    @Override\n    public Schema snapshot(SchemaVersion version) {\n      return illegal();\n    }\n\n    @SuppressWarnings(\"TypeParameterUnusedInFormals\")\n    private static <T> T illegal() {\n      throw new IllegalStateException(\"Beam JDBC connection has not been initialized\");\n    }\n  }\n}\n","sourceCodeStart":210,"sourceCodeEnd":232,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/BeamCalciteSchemaFactory.java#L210-L232","documentation":"BeamCalciteSchemaFactory's inner Schema implementation is a placeholder that only works after the JDBC connection has been initialized. Every metadata method (getTable, getType, functions, etc.) calls illegal(), which throws IllegalStateException until initialization occurs.","triggerScenarios":"Using a BeamCalciteConnection's schema object before executing a statement or completing connection initialization, e.g. calling connection.getRootSchema().getTable(...) or schema.getTableNames() on a fresh Beam JDBC connection.","commonSituations":"Inspection code that grabs the schema right after DriverManager.getConnection but before running a query, frameworks probing schema metadata early, tests using the raw schema object.","solutions":["Initialize the connection first: execute a statement or use the documented init path before touching the schema","Obtain schema metadata through standard JDBC DatabaseMetaData instead of the internal Schema object","Ensure you are using a Beam JDBC connection wired through BeamSqlEnv, not an unconstructed default instance"],"exampleFix":"// before\nSchema schema = ((BeamCalciteConnection) conn).getRootSchema();\nschema.getTableNames(); // throws\n// after\ntry (Statement stmt = conn.createStatement()) {\n  stmt.executeQuery(\"SELECT 1\"); // initializes the connection\n}\n// then access schema metadata","handlingStrategy":"try-catch","validationCode":"boolean initialized = false; // set true after first successful statement execution","typeGuard":null,"tryCatchPattern":"try { schema.getTableNames(); } catch (IllegalStateException e) { initializeConnection(); schema.getTableNames(); }","preventionTips":["Execute at least one statement before schema introspection","Use JDBC DatabaseMetaData for metadata","Don't cache Schema references from pre-init connections"],"tags":["jdbc","sql","initialization"],"backgroundTag":"invalid-state-transition","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}