{"record":{"id":"2d37e37b8c62191d","repo":"pentaho/pentaho-kettle","slug":"error-connecting-to-the-repository","errorCode":null,"errorMessage":"Error connecting to the repository!","messagePattern":"Error connecting to the repository!","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"critical","filePath":"engine/src/main/java/org/pentaho/di/repository/kdr/delegates/KettleDatabaseRepositoryConnectionDelegate.java","lineNumber":159,"sourceCode":"    try {\n      database.initializeVariablesFrom( null );\n      database.connect();\n      if ( !ignoreVersion ) {\n        verifyVersion();\n      }\n      setAutoCommit( false );\n      repository.setConnected( true );\n      /*\n       * Done lazily now.\n       *\n       * if (!no_lookup) { try { repository.connectionDelegate.setLookupStepAttribute();\n       * repository.connectionDelegate.setLookupTransAttribute();\n       * repository.connectionDelegate.setLookupJobEntryAttribute();\n       * repository.connectionDelegate.setLookupJobAttribute(); } catch (KettleException dbe) { throw new\n       * KettleException(\"Error setting lookup prep.statements\", dbe); } }\n       */\n    } catch ( KettleException e ) {\n      throw new KettleException( \"Error connecting to the repository!\", e );\n    }\n  }\n\n  /**\n   * Get the required repository version for this version of Kettle.\n   *\n   * @return the required repository version for this version of Kettle.\n   */\n  public static final String getRequiredVersion() {\n    return REQUIRED_MAJOR_VERSION + \".\" + REQUIRED_MINOR_VERSION;\n  }\n\n  protected void verifyVersion() throws KettleException {\n    RowMetaAndData lastUpgrade = null;\n    String versionTable =\n      databaseMeta.getQuotedSchemaTableCombination( null, KettleDatabaseRepository.TABLE_R_VERSION );\n    try {\n      lastUpgrade = callRead( () ->","sourceCodeStart":141,"sourceCodeEnd":177,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/repository/kdr/delegates/KettleDatabaseRepositoryConnectionDelegate.java#L141-L177","documentation":"Wrapper KettleException thrown by connect when any KettleException occurs while establishing the repository database connection, initializing variables, connecting the underlying Database, or verifying the repository version. The cause holds the real error (bad credentials, unreachable DB, wrong driver, unsupported version).","triggerScenarios":"database.connect() failing (wrong host/port/credentials), verifyVersion() throwing, or variable initialization failing during repository.connect(...).","commonSituations":"Database server down, wrong JDBC URL or driver not on classpath, invalid repository credentials, firewall blocking the DB port.","solutions":["Inspect getCause() for the underlying database/driver error","Test the JDBC connection parameters (host, port, database name, user, password) independently","Ensure the correct JDBC driver jar is on the classpath","Verify the database is reachable (ping/telnet host:port) and repository tables exist"],"exampleFix":"// before\nrepository.connect(user, pass); // opaque failure\n\n// after\ntry {\n  repository.connect(user, pass);\n} catch (KettleException e) {\n  log.error(\"Repo connect failed\", e.getCause()); // real JDBC error\n  throw e;\n}","handlingStrategy":"try-catch","validationCode":"// pre-check reachability before repository.connect\ntry (Socket s = new Socket(dbHost, dbPort)) { /* reachable */ }","typeGuard":null,"tryCatchPattern":"try { repository.connect(u, p); } catch (KettleException e) { log.error(\"Connect failed: \", e.getCause()); throw e; } // inspect cause for JDBC error","preventionTips":["Validate JDBC URL/credentials with a plain DB client first","Ensure JDBC drivers are on the classpath","Check network/firewall access to the DB host:port","Verify repository tables exist before connecting"],"tags":["repository","connection","database"],"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"}