pentaho/pentaho-kettle · error · KettleException

TransMeta.Log.UnableToReadClustersFromRepository

Error message

TransMeta.Log.UnableToReadClustersFromRepository

What it means

Thrown by readClusters() in the KettleDatabaseRepositoryTransDelegate when reading cluster schemas (partitioned cluster definitions) for a transformation from the database repository fails with a KettleDatabaseException. It wraps the low-level JDBC/repository error in a KettleException with this message. It is part of the shared-objects loading step invoked via readTransSharedObjects().

Solutions

  1. Verify database connectivity and that the repository tables (R_CLUSTER, R_CLUSTER_SLAVE) exist and are reachable
  2. Run the repository upgrade/repair tools so the schema matches your Pentaho version
  3. Grant the repository DB user SELECT privileges on the cluster tables
  4. Check the wrapped KettleDatabaseException (cause) for the exact SQL error and fix accordingly

Example fix

// before
TransMeta transMeta = new TransMeta(rep, transName, directory);
// cluster load throws KettleException

// after
try {
  TransMeta transMeta = new TransMeta(rep, transName, directory);
} catch (KettleException e) {
  logError("Failed to read clusters from repository: " + e.getCause(), e);
  // repair repository schema / reconnect, then retry
}
Defensive patterns

Strategy: try-catch

Validate before calling

// Java: verify repository connectivity and tables before loading
DatabaseMeta dbMeta = repository.getDatabaseMeta();
if (!dbMeta.testConnection(logger).toUpperCase().contains("OK")) {
  throw new IllegalStateException("Repository DB unreachable");
}

Try / catch

try {
  transMeta = rep.loadTransformation(...);
} catch (KettleException e) {
  log.warn("Cluster schema load failed: " + e.getCause(), e);
  transMeta = new TransMeta(); // fall back / repair repo, retry
}

Prevention

When it happens

Trigger: Calling TransMeta loading from a KettleDatabaseRepository (readTransSharedObjects -> readClusters) when the underlying query on R_CLUSTER / R_CLUSTER_SLAVE tables fails: table missing, connection dropped, SQL syntax/permission error, or corrupted cluster rows.

Common situations: Repository schema out of date (created with a different Kettle version), database user lacking SELECT grants on cluster tables, network drop mid-load, or manually edited repository tables.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/repository/kdr/delegates/KettleDatabaseRepositoryTransDelegate.java:987

  public void readClusters( TransMeta transMeta, boolean overWriteShared ) throws KettleException {
    try {
      ObjectId[] dbids = repository.getClusterIDs( false );
      for ( int i = 0; i < dbids.length; i++ ) {
        ClusterSchema clusterSchema = repository.loadClusterSchema( dbids[i], transMeta.getSlaveServers(), null );
        clusterSchema.shareVariablesWith( transMeta );
        // Check if there already is one in the transformation
        ClusterSchema check = transMeta.findClusterSchema( clusterSchema.getName() );
        if ( check == null || overWriteShared ) {
          if ( !Utils.isEmpty( clusterSchema.getName() ) ) {
            transMeta.addOrReplaceClusterSchema( clusterSchema );
            if ( !overWriteShared ) {
              clusterSchema.setChanged( false );
            }
          }
        }
      }
    } catch ( KettleDatabaseException dbe ) {
      throw new KettleException(
        BaseMessages.getString( PKG, "TransMeta.Log.UnableToReadClustersFromRepository" ), dbe );
    }
  }

  /**
   * Read the partitions in the repository and add them to this transformation if they are not yet present.
   *
   * @param transMeta
   *          The transformation to load into.
   * @param overWriteShared
   *          if an object with the same name exists, overwrite
   * @throws KettleException
   */
  public void readPartitionSchemas( TransMeta transMeta, boolean overWriteShared ) throws KettleException {
    try {
      ObjectId[] dbids = repository.getPartitionSchemaIDs( false );
      for ( int i = 0; i < dbids.length; i++ ) {
        PartitionSchema partitionSchema = repository.loadPartitionSchema( dbids[i], null ); // Load last version

View on GitHub (pinned to f3058517a1)