pentaho/pentaho-kettle · error · KettleException

Unable to open repository connection

Error message

Unable to open repository connection

What it means

After SlaveServerConfig.openRepository finds the repository metadata and instantiates the Repository plugin, repository.connect(username, password) failing (bad credentials, network, driver missing) is caught and rethrown as the less specific KettleException("Unable to open repository connection") with the real cause chained. It signals the repository was identified but a live connection could not be established.

Solutions

  1. Inspect the chained cause (e) for the real driver/SQL/network error.
  2. Verify repository username and password in the Carte config are current; update after password rotations.
  3. Test connectivity from the Carte host to the repository database (ping/telnet host:port, check firewall).
  4. Ensure the repository DB's JDBC driver jar is in the Carte lib/ directory.
  5. Re-test credentials by connecting in Spoon on the Carte host itself.

Example fix

// before: carte-config.xml with stale password
<repository username="admin" password="oldPass" .../>

// after
<repository username="admin" password="newRotatedPass" .../>
Defensive patterns

Strategy: retry

Validate before calling

// pre-flight: verify the repository DB is reachable and credentials work
try (Connection c = DriverManager.getConnection(repoDbUrl, user, pass)) {
  if (!c.isValid(5)) throw new SQLException("cannot connect to repository DB");
}

Try / catch

int attempts = 0;
while (true) {
  try { slaveServerConfig.getRepository(); break; }
  catch (KettleException e) {
    if (++attempts > 3 || e.getCause() instanceof AuthenticationException) throw e;
    Thread.sleep(5000L * attempts); // transient network only
  }
}

Prevention

When it happens

Trigger: repository.connect() throwing for any reason during openRepository: wrong username/password for the repository, the repository's backing database is down, the JDBC driver for the repository DB is not on Carte's classpath, or repository.init fails.

Common situations: Password changed after a policy rotation and carte-config.xml still has the old one; firewall blocking Carte host to the repository DB; ojdbc/postgresql driver jar missing from lib/ on the Carte server; repository database upgraded and driver incompatible.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

AI-assisted analysis of pentaho/pentaho-kettle@f3058517a1 (2026-09-13). Data as JSON: /api/errors/cba2c842906c250d. Report an issue: GitHub.

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/www/SlaveServerConfig.java:292

  private void openRepository( String repositoryId ) throws KettleException {
    try {

      RepositoriesMeta repositoriesMeta = new RepositoriesMeta();
      repositoriesMeta.readData();
      repositoryMeta = repositoriesMeta.findRepository( repositoryId );
      if ( repositoryMeta == null ) {
        throw new KettleException( "Unable to find repository: " + repositoryId );
      }
      PluginRegistry registry = PluginRegistry.getInstance();
      repository = registry.loadClass( RepositoryPluginType.class, repositoryMeta, Repository.class );
      repository.init( repositoryMeta );
      repository.connect( repositoryUsername, repositoryPassword );

      LogChannel.GENERAL.logBasic( "Connected to repository '" + repository.getName() + "'" );

    } catch ( Exception e ) {
      throw new KettleException( "Unable to open repository connection", e );
    }
  }

  public void readAutoSequences() throws KettleException {
    if ( autoSequence == null ) {
      return;
    }

    Database database = null;

    try {
      DatabaseMeta databaseMeta = autoSequence.getDatabaseMeta();
      LoggingObjectInterface loggingInterface =
        new SimpleLoggingObject( "auto-sequence", LoggingObjectType.GENERAL, null );
      database = new Database( loggingInterface, databaseMeta );
      database.connect();
      String schemaTable =
        databaseMeta.getQuotedSchemaTableCombination( autoSequence.getSchemaName(), autoSequence.getTableName() );

View on GitHub (pinned to f3058517a1)