pentaho/pentaho-kettle · error · KettleException

At this time we don't support the use of multiple cluster…

Error message

At this time we don't support the use of multiple cluster schemas in one and the same transformation.

What it means

TransSplitter.checkClusterConfiguration throws this when the transMeta uses more than one cluster schema. Pentaho/Kettle clustering only supports assigning a single cluster schema per transformation, since all slaves must come from one schema definition. It is a deliberate design guard, not a transient failure.

Solutions

Assign all clustered steps in the transformation to the same cluster schema.
Remove the cluster schema from steps that do not need clustering so only one schema remains in use.
Split the transformation into two transformations (each with one cluster schema) chained via a slave-server hop.

Example fix

// before
stepA.setClusterSchema(schemaAlpha);
stepB.setClusterSchema(schemaBeta); // throws
// after
stepA.setClusterSchema(sharedSchema);
stepB.setClusterSchema(sharedSchema);

Defensive patterns

Strategy: validation

Validate before calling

Set<String> schemas = new HashSet<>();
for (StepMeta step : transMeta.getSteps()) {
  if (step.getClusterSchema() != null) schemas.add(step.getClusterSchema().getName());
}
if (schemas.size() > 1) throw new IllegalStateException("Use at most one cluster schema: " + schemas);

Try / catch

try { transSplitter.executeClustered(); }
catch (KettleException e) { if (e.getMessage().contains("multiple cluster schemas")) { fixSchemaAssignment(); } else throw e; }

Prevention

Standardize on one cluster schema per transformation
Review step properties after copy-pasting from other transformations
Add a metadata audit before clustered execution

When it happens

Trigger: Calling TransSplitter.execute()/splitOriginalTransformation() when two or more steps in the transformation are assigned to different cluster schemas (checkClusterConfiguration collects schemas into a map and throws when map.size() > 1).

Common situations: Teams combining steps clustered on one schema with steps clustered on another after merging transformations; copy-pasting steps from another clustered transformation that kept its old schema reference.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/cluster/TransSplitter.java:211

        List<SlaveServer> slaves = clusterSchema.getSlaveServersFromMasterOrLocal();
        int count = 0;
        for ( int s = 0; s < slaves.size(); s++ ) {
          if ( !slaves.get( s ).isMaster() ) {
            count++;
          }
        }
        if ( count <= 0 ) {
          throw new KettleException( "At least one slave server is required to be present in cluster schema ["
            + clusterSchema + "]" );
        }
      }
    }
    if ( map.size() == 0 ) {
      throw new KettleException(
        "No cluster schemas are being used.  As such it is not possible to split and cluster this transformation." );
    }
    if ( map.size() > 1 ) {
      throw new KettleException(
        "At this time we don't support the use of multiple cluster schemas in one and the same transformation." );
    }
  }

  private String getWriterName( ClusterSchema clusterSchema, SlaveServer sourceSlaveServer, String sourceStepname,
    int sourceStepCopy, SlaveServer targetSlaveServer, String targetStepName, int targetStepCopy ) throws Exception {
    return "Writer : "
      + getPort(
        clusterSchema, sourceSlaveServer, sourceStepname, sourceStepCopy, targetSlaveServer, targetStepName,
        targetStepCopy );
  }

  private String getReaderName( ClusterSchema clusterSchema, SlaveServer sourceSlaveServer, String sourceStepname,
    int sourceStepCopy, SlaveServer targetSlaveServer, String targetStepName, int targetStepCopy ) throws Exception {
    return "Reader : "
      + getPort(
        clusterSchema, sourceSlaveServer, sourceStepname, sourceStepCopy, targetSlaveServer, targetStepName,
        targetStepCopy );

View on GitHub (pinned to f3058517a1)