{"record":{"id":"a2716768d6f3ab4b","repo":"pentaho/pentaho-kettle","slug":"database-exception-connectiontestfailed","errorCode":null,"errorMessage":"Database.Exception.ConnectionTestFailed","messagePattern":"Database\\.Exception\\.ConnectionTestFailed","errorType":"exception","errorClass":"KettleDatabaseException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/pentaho/di/core/database/Database.java","lineNumber":632,"sourceCode":"      loadStaticDriver( classname, plugin );\n    }\n\n    try {\n      String url = resolveUrl( partitionId );\n      String[] credentials = resolveCredentials( partitionId );\n      url = applyCredentialsToProperties( url, credentials[0], credentials[1], properties );\n\n      log.logDetailed( \"Acquiring JDBC connection for database [\" + databaseMeta.getName() + \"] using driver class [\" + classname + \"]...\" );\n      long startJdbc = System.currentTimeMillis();\n      if ( usingDynamicDriver ) {\n        connection = openConnectionViaDynamicDriver( jdbcDriverClass, url, properties );\n      } else {\n        connection = DriverManager.getConnection( url, properties );\n      }\n      log.logDetailed( \"JDBC connection acquired for database [\" + databaseMeta.getName() + \"] in \" + ( System.currentTimeMillis() - startJdbc ) + \" ms\" );\n    } catch ( SQLException sqlException ) {\n      closeDynamicClassLoader();\n      throw new KettleDatabaseException(\n        BaseMessages.getString( PKG, \"Database.Exception.ConnectionTestFailed\", toString() ), sqlException );\n    } catch ( Exception e ) {\n      closeDynamicClassLoader();\n      throw new KettleDatabaseException( \"Error connecting to database: (using class \" + classname + \")\", e );\n    }\n  }\n\n  private void loadStaticDriver( String classname, PluginInterface plugin ) throws KettleDatabaseException {\n    try {\n      synchronized ( java.sql.DriverManager.class ) {\n        ClassLoader classLoader = PluginRegistry.getInstance().getClassLoader( plugin );\n        Class<?> driverClass = classLoader.loadClass( classname );\n        // Only need DelegatingDriver for drivers not from our classloader\n        if ( driverClass.getClassLoader() != this.getClass().getClassLoader() ) {\n          registerDelegatingDriver( driverClass );\n        } else {\n          // Trigger static register block in driver class\n          Class.forName( classname );","sourceCodeStart":614,"sourceCodeEnd":650,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/core/src/main/java/org/pentaho/di/core/database/Database.java#L614-L650","documentation":"connectUsingClass translates SQLExceptions thrown while acquiring the JDBC connection via the database plugin's driver class into KettleDatabaseException with the i18n message \"Database.Exception.ConnectionTestFailed\" (parameterized with the database description). It signals the driver was loaded but the connection itself was refused/failed.","triggerScenarios":"SQLException from dataSource.getConnection/DriverManager.getConnection in connectUsingClass — bad credentials, unreachable server, unknown database, SSL handshake failure, or connection pool exhaustion.","commonSituations":"Typos in host/port/db name, database server down or firewalled, expired/locked DB account, TLS misconfiguration, wrong driver/URL combination for the database type.","solutions":["Read the wrapped SQLException (cause) for the vendor error code and message","Validate host, port, database name, user and password in the connection dialog/DatabaseMeta","Test network reachability (ping/telnet to host:port) from the running host","Check account status and SSL/TLS requirements on the database server"],"exampleFix":"// before\nurl = \"jdbc:mysql://localhost\"; // missing db/port\n\n// after\nurl = \"jdbc:mysql://localhost:3306/mydb?useSSL=true\";","handlingStrategy":"retry","validationCode":"// pre-connect probe\ntry ( Socket s = new Socket() ) {\n  s.connect( new InetSocketAddress( host, port ), 3000 ); // throws if unreachable\n}","typeGuard":null,"tryCatchPattern":"try {\n  db.connect();\n} catch ( KettleDatabaseException e ) {\n  SQLException sql = findCauseOfType( e, SQLException.class );\n  if ( sql != null && isTransient( sql.getErrorCode() ) ) retryConnect( db );\n  else log.error( \"Connection test failed: \" + sql, sql );\n}","preventionTips":["Store credentials securely and validate them periodically","Use the 'Test' connection button/equivalent before production runs","Monitor database availability before batch jobs","Match URL parameters (SSL, timeouts) to server requirements"],"tags":["jdbc","sql-exception","connection-test-failed"],"backgroundTag":"connection-refused","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}