{"record":{"id":"f479f014af843608","repo":"apache/druid","slug":"jdbc-driver-jar-files-missing-in-the-classpath","errorCode":null,"errorMessage":"JDBC driver JAR files missing in the classpath","messagePattern":"JDBC driver JAR files missing in the classpath","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions-core/lookups-cached-single/src/main/java/org/apache/druid/server/lookup/jdbc/JdbcDataFetcher.java","lineNumber":257,"sourceCode":"                    }\n                    catch (SQLException e) {\n                      // at least try to log it so we don't swallow exceptions\n                      LOGGER.error(e, \"Unable to reset connection read-only state\");\n                    }\n                  }\n                }\n            )\n    );\n  }\n\n  private <T> T runWithMissingJdbcJarHandler(Supplier<T> supplier)\n  {\n    try {\n      return supplier.get();\n    }\n    catch (UnableToObtainConnectionException e) {\n      if (e.getMessage().contains(\"No suitable driver found\")) {\n        throw new ISE(\n            e,\n            \"JDBC driver JAR files missing in the classpath\"\n        );\n      } else {\n        throw e;\n      }\n    }\n  }\n}\n","sourceCodeStart":239,"sourceCodeEnd":267,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/extensions-core/lookups-cached-single/src/main/java/org/apache/druid/server/lookup/jdbc/JdbcDataFetcher.java#L239-L267","documentation":"JdbcDataFetcher.runWithMissingJdbcJarHandler() wraps execution of JDBC lookups. When the JDBC driver reports 'No suitable driver found' (UnableToObtainConnectionException), it rethrows as an ISE saying the driver JARs are missing from the classpath — a clearer message for the standard case of an unloaded JDBC driver.","triggerScenarios":"Using a JDBC-based lookup (JdbcDataFetcher) without the corresponding JDBC driver JAR loaded as a Druid extension, so DriverManager cannot find a driver for the JDBC URL.","commonSituations":"Configuring a JDBC lookup but forgetting to load the mysql-metadata-storage or postgresql extension; driver JAR present but not on the classpath of the task/router process; driver registration blocked by classloader isolation.","solutions":["Add the JDBC driver JAR to extensions/ and load the corresponding extension (e.g. mysql-metadata-storage)","Ensure druid.extensions.loadList includes the extension providing the driver","Verify driver compatibility with the Java version and JDBC URL (jdbc:mysql: vs jdbc:postgresql:)"],"exampleFix":"// before (no extension loaded)\ndruid.extensions.loadList=[\"druid-lookups-cached-single\"]\n// after\ndruid.extensions.loadList=[\"druid-lookups-cached-single\", \"mysql-metadata-storage\"]","handlingStrategy":"validation","validationCode":"try { Class.forName(\"com.mysql.cj.jdbc.Driver\"); } catch (ClassNotFoundException e) { throw new IllegalStateException(\"MySQL driver not on classpath; install extension\"); }","typeGuard":null,"tryCatchPattern":"try { return fetcher.fetch(); } catch (ISE e) { if (e.getMessage().contains(\"JDBC driver JAR files missing\")) { throw new ConfigurationException(\"Load the JDBC driver extension before using JDBC lookups\"); } throw e; }","preventionTips":["Always deploy the JDBC driver JAR together with lookups-cached-single/jdbc extensions","Smoke-test JDBC connectivity at startup (connection pool init) to fail fast","Pin driver versions in your Druid image/deployment artifacts"],"tags":["jdbc","classpath","driver","lookup"],"backgroundTag":"missing-dependency","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}