{"record":{"id":"3728d98b13f96346","repo":"apache/beam","slug":"unexpected-null-when-creating-synthetic-beam-jdbcdriver","errorCode":null,"errorMessage":"Unexpected null when creating synthetic Beam JdbcDriver","messagePattern":"Unexpected null when creating synthetic Beam JdbcDriver","errorType":"exception","errorClass":"SQLException","httpStatus":null,"severity":"error","filePath":"sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/JdbcDriver.java","lineNumber":188,"sourceCode":"  private static JdbcConnection getConnection(PipelineOptions options) {\n    Properties properties = new Properties();\n    properties.setProperty(\n        SCHEMA_FACTORY.camelName(), BeamCalciteSchemaFactory.Empty.class.getName());\n    BeamSqlPipelineOptions sqlOptions = options.as(BeamSqlPipelineOptions.class);\n    if (sqlOptions != null) {\n      Map<String, String> calciteConnectionProperties = sqlOptions.getCalciteConnectionProperties();\n      if (calciteConnectionProperties != null) {\n        properties.putAll(calciteConnectionProperties);\n      }\n    }\n    JdbcConnection connection;\n    try {\n      connection = (JdbcConnection) INSTANCE.connect(CONNECT_STRING_PREFIX, properties);\n      // Normally, #connect is allowed to return null when the URL is not suitable. Here, however,\n      // we are\n      // deliberately passing a bogus URL to instantiate a connection, so it should never be null.\n      if (connection == null) {\n        throw new SQLException(\"Unexpected null when creating synthetic Beam JdbcDriver\");\n      }\n    } catch (SQLException e) {\n      throw new RuntimeException(e);\n    }\n    connection.setPipelineOptions(options);\n    return connection;\n  }\n}\n","sourceCodeStart":170,"sourceCodeEnd":197,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/JdbcDriver.java#L170-L197","documentation":"JdbcDriver.getConnection creates a synthetic JdbcConnection by calling the driver's connect() with a deliberately bogus URL; Calcite's connect may legally return null for unsuitable URLs, but here the URL is fixed and known-good, so a null indicates an internal driver state problem. The method throws SQLException (which the caller wraps in RuntimeException) to fail fast rather than NPE later.","triggerScenarios":"Calling JdbcDriver.getConnection(pipelineOptions) (from the connection() factory) when Calcite's JdbcDriver.connect returns null for the internal CONNECT_STRING_PREFIX — typically a broken/changed Calcite driver registration or incompatible calcite JDBC version on the classpath.","commonSituations":"Classpath conflicts where another JDBC driver or a different Calcite version claims/handles the 'jdbc:beam:' prefix; shading that drops the driver registration; calcite-core version skew after dependency upgrades.","solutions":["Check the classpath for conflicting Calcite versions (mvn dependency:tree) and pin a single calcite-core version matching Beam's SQL module.","Verify the Beam JdbcDriver is the driver handling the internal CONNECT_STRING_PREFIX and is not shadowed by another driver registered earlier.","If you hit this without modifying Beam internals, report/inspect for a shading or dependency-injection issue in your build.","Catch the resulting RuntimeException from connection() and surface a clear classpath-diagnosis message to users."],"exampleFix":"// before (caller of JdbcDriver.connection(options))\nJdbcConnection conn = JdbcDriver.connection(options);\n// after\ntry {\n  JdbcConnection conn = JdbcDriver.connection(options);\n} catch (RuntimeException e) {\n  throw new IllegalStateException(\n      \"Beam JDBC synthetic connection failed; check for duplicate calcite versions on the classpath\", e);\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  JdbcConnection conn = JdbcDriver.connection(options);\n} catch (RuntimeException e) {\n  throw new IllegalStateException(\"Beam synthetic JDBC connection failed; check calcite classpath\", e);\n}","preventionTips":["Pin exactly one calcite-core version; run mvn dependency:tree to detect conflicts.","Avoid shading calcite-core without merging driver/service metadata.","Test Beam SQL connection creation early in application startup."],"tags":["java","jdbc","calcite","internal-invariant","beam-sql"],"backgroundTag":"internal-invariant-violation","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"}