{"record":{"id":"2f6e1817ee5cc94e","repo":"pentaho/pentaho-kettle","slug":"error-occurred-while-trying-to-connect-to-the-database","errorCode":null,"errorMessage":"Error occurred while trying to connect to the database","messagePattern":"Error occurred while trying to connect to the database","errorType":"exception","errorClass":"KettleDatabaseException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/pentaho/di/core/database/Database.java","lineNumber":532,"sourceCode":"        }\n      } else {\n        // using non-jndi and non-pooled connection -- just a simple JDBC\n        connectUsingClass( databaseMeta.getDriverClass(), partitionId );\n      }\n\n      // See if we need to execute extra SQL statement...\n      String sql = environmentSubstitute( databaseMeta.getConnectSQL() );\n\n      // only execute if the SQL is not empty, null and is not just a bunch of\n      // spaces, tabs, CR etc.\n      if ( !Utils.isEmpty( sql ) && !Const.onlySpaces( sql ) ) {\n        execStatements( sql );\n        if ( log.isDetailed() ) {\n          log.logDetailed( \"Executed connect time SQL statements:\" + Const.CR + sql );\n        }\n      }\n    } catch ( Exception e ) {\n      throw new KettleDatabaseException( \"Error occurred while trying to connect to the database\", e );\n    }\n  }\n\n  public void initializeConnectionDataSource( String partitionId ) throws KettleDatabaseException {\n\n    try {\n      DataSourceProviderInterface dsp = DataSourceProviderFactory.getDataSourceProviderInterface();\n      if ( dsp == null ) {\n        // since DataSourceProviderFactory is initialised with new DatabaseUtil(),\n        // this assignment is correct\n        dsp = new DatabaseUtil();\n      }\n\n      if ( databaseMeta.getAccessType() == DatabaseMeta.TYPE_ACCESS_JNDI ) {\n        this.dataSource = getJNDIDataSource( dsp );\n      } else if ( databaseMeta.isUsingConnectionPool() ) {\n        this.dataSource = getPoolingDataSource( partitionId, dsp );\n      }","sourceCodeStart":514,"sourceCodeEnd":550,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/core/src/main/java/org/pentaho/di/core/database/Database.java#L514-L550","documentation":"normalConnect wraps any exception thrown while establishing the JDBC connection (driver load, DriverManager/connection creation, connect-time SQL statements) into KettleDatabaseException(\"Error occurred while trying to connect to the database\", cause). The real failure reason is always in the cause chain.","triggerScenarios":"Any Exception raised inside normalConnect's try block: driver class loading via connectUsingClass, SQLException from DriverManager, or exceptions from execStatements running connect-time SQL.","commonSituations":"Wrong host/port, database down, bad credentials, missing JDBC driver jar, invalid URL in DatabaseMeta, or failing connect-time SQL scripts.","solutions":["Read the wrapped cause exception for the actual root failure and fix accordingly","Verify host, port, database name, username and password in the DatabaseMeta","Ensure the JDBC driver jar is on the classpath or in the database plugin's lib directory","Test the connection from the same machine with a plain JDBC client to rule out network/firewall issues"],"exampleFix":"// before\ndb.connect(); // opaque message\n\n// after\ntry {\n  db.connect();\n} catch ( KettleDatabaseException e ) {\n  log.error( \"Connect failed: \" + e.getCause(), e );\n}","handlingStrategy":"try-catch","validationCode":"// pre-check reachable endpoint before connect\nInetSocketAddress addr = new InetSocketAddress( host, port );\nif ( addr.isUnresolved() ) throw new IllegalStateException( \"Unknown host \" + host );","typeGuard":null,"tryCatchPattern":"try {\n  db.connect();\n} catch ( KettleDatabaseException e ) {\n  Throwable root = e.getCause();\n  log.error( \"DB connect failed: \" + ( root != null ? root.getMessage() : e.getMessage() ), root );\n}","preventionTips":["Always log getCause() of KettleDatabaseException, not just its message","Validate connection parameters before connecting","Keep JDBC drivers up to date and on the classpath","Prefer connect() over manual normalConnect to retain consistent wrapping"],"tags":["database","jdbc","connection-failure"],"backgroundTag":"database-connection-failed","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"}