{"record":{"id":"18911ebb15c9ab3b","repo":"OtterMind/Chat2DB","slug":"jdbc-driver-downloadfailed","errorCode":"jdbc.driver.downloadFailed","errorMessage":"jdbc.driver.downloadFailed","messagePattern":"jdbc\\.driver\\.downloadFailed","errorType":"exception","errorClass":"BusinessException","httpStatus":null,"severity":"error","filePath":"chat2db-community-server/chat2db-community-domain/chat2db-community-domain-core/src/main/java/ai/chat2db/community/domain/core/impl/db/DbJdbcDriverServiceImpl.java","lineNumber":126,"sourceCode":"\n    @Override\n    public void downloadBuiltinDrivers(String dbType) throws IOException {\n        DBConfig dbConfig = queryDbConfig(dbType);\n        List<DriverConfig> driverConfigList = dbConfig.getDriverConfigList();\n        for (DriverConfig driverConfig : driverConfigList) {\n            List<String> downloadJdbcDriverUrls = driverConfig.getDownloadJdbcDriverUrls();\n            for (String downloadJdbcDriverUrl : downloadJdbcDriverUrls) {\n                JdbcJarUtils.download(downloadJdbcDriverUrl);\n            }\n        }\n    }\n\n    @Override\n    public void downloadBuiltinDriversOrThrow(String dbType) {\n        try {\n            downloadBuiltinDrivers(dbType);\n        } catch (IOException e) {\n            throw new BusinessException(\"jdbc.driver.downloadFailed\", new Object[]{e.getMessage()}, e);\n        }\n    }\n\n    @Override\n    public void downloadStartupDrivers() {\n        List<String> urls = new ArrayList<>();\n        Chat2DBContext.PLUGIN_MAP.forEach((k, v) -> {\n            try {\n                DBConfig dbConfig = v.getDBConfig();\n                if (dbConfig != null) {\n                    dbConfig.getDriverConfigList().forEach(driverConfig -> {\n                        if (driverConfig != null && driverConfig.getDownloadJdbcDriverUrls() != null\n                                && !driverConfig.getDownloadJdbcDriverUrls().isEmpty()\n                                && \"MYSQL\".equals(driverConfig.getDbType())) {\n                            urls.addAll(driverConfig.getDownloadJdbcDriverUrls());\n                        }\n                    });\n                }","sourceCodeStart":108,"sourceCodeEnd":144,"githubUrl":"https://github.com/OtterMind/Chat2DB/blob/5ee1e990e73fbcae1969dc554be254fedb3ab888/chat2db-community-server/chat2db-community-domain/chat2db-community-domain-core/src/main/java/ai/chat2db/community/domain/core/impl/db/DbJdbcDriverServiceImpl.java#L108-L144","documentation":"Thrown by DbJdbcDriverServiceImpl.downloadBuiltinDriversOrThrow to wrap an IOException from downloadBuiltinDrivers (which loops driverConfig download URLs and calls JdbcJarUtils.download). The underlying cause is a network/IO failure fetching the JDBC driver jar. The code 'jdbc.driver.downloadFailed' is NOT a defined i18n key, so the user-facing message becomes the raw 'jdbc.driver.downloadFailed : no message.' with e.getMessage() effectively lost from the resolved text (the arg is passed but there is no message template to interpolate).","triggerScenarios":"Connecting to a datasource whose driver jar must be downloaded (not bundled) and the download URL is unreachable (404, DNS, proxy, timeout, TLS, auth). Triggered at connection-establishment time when drivers are fetched on demand.","commonSituations":"Offline/air-gapped host with no internet egress; a driver download host that moved or requires a proxy; a corporate firewall blocking the jar URL; a stale driverConfig pointing at an old maven/CDN path.","solutions":["Verify the host can reach each URL in driverConfig.getDownloadJdbcDriverUrls() (curl the first URL).","Configure the network proxy / allow-list for the driver download host.","Pre-place the driver jar in JdbcDriverConstants.DRIVER_LIB_PATH so no download is needed.","Add the i18n key 'jdbc.driver.downloadFailed=Failed to download JDBC driver: {0}' so the IOException message is surfaced."],"exampleFix":"// before\nthrow new BusinessException(\"jdbc.driver.downloadFailed\", new Object[]{e.getMessage()}, e);\n// renders: \"jdbc.driver.downloadFailed : no message.\"\n\n// after (add to messages_en_US.properties)\n// jdbc.driver.downloadFailed=Failed to download JDBC driver: {0}\n// renders: \"Failed to download JDBC driver: <io message>\"","handlingStrategy":"retry","validationCode":"for (String url : driverConfig.getDownloadJdbcDriverUrls()) {\n    try { JdbcJarUtils.download(url); break; }\n    catch (IOException ignore) { /* try next mirror */ }\n}","typeGuard":null,"tryCatchPattern":"try {\n    driverService.downloadBuiltinDriversOrThrow(dbType);\n} catch (BusinessException e) { // code jdbc.driver.downloadFailed\n    // surface e.getCause().getMessage(); prompt proxy/offline driver placement\n}","preventionTips":["Pre-stage required driver jars in DRIVER_LIB_PATH for offline hosts.","Configure outbound proxy/allow-list for driver download hosts.","Add i18n key jdbc.driver.downloadFailed so the cause message is visible."],"tags":["jdbc-driver","network","connection","i18n-missing-key"],"backgroundTag":null,"analyzedSha":"5ee1e990e73fbcae1969dc554be254fedb3ab888","analyzedAt":"2026-08-14T07:05:03.077Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}