pentaho/pentaho-kettle · error · KettleException

At least one slave server is required to be present in…

Error message

At least one slave server is required to be present in cluster schema [" + clusterSchema + "]

What it means

TransSplitter.checkClusterConfiguration() counts non-master servers in each cluster schema and throws KettleException 'At least one slave server is required to be present in cluster schema [<schema>]' when the count of actual slaves (isMaster()==false) is zero. A cluster with only a master has nothing to distribute work to.

Solutions

  1. Add at least one non-master slave server to the cluster schema.
  2. Un-check 'master' on servers that should be slaves, keeping exactly one master.
  3. If only one node is available, run the transformation without clustering.
  4. Pre-validate schema contents (>=1 master and >=1 slave) before clustered execution.

Example fix

// before
slaveA.setMaster(true); slaveB.setMaster(true); // no slaves
// after
slaveA.setMaster(true); slaveB.setMaster(false); // one master, one slave
Defensive patterns

Strategy: validation

Validate before calling

long slaves = cs.getSlaveServers().stream().filter(s -> !s.isMaster()).count();
if (slaves == 0) throw new IllegalStateException("Cluster schema '" + cs.getName() + "' needs at least one non-master slave");

Try / catch

try {
  splitter.splitOriginalTransformation();
} catch (KettleException e) {
  if (e.getMessage().startsWith("At least one slave server is required")) {
    // add a slave server to the schema
  }
}

Prevention

When it happens

Trigger: checkClusterConfiguration() finding a cluster schema whose servers are all masters (count of non-master slaves <= 0).

Common situations: Building a cluster schema with a single server marked as master; accidentally marking all servers as masters while debugging; removing slave entries but keeping the schema referenced by steps.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

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

        // Remember cluster details while we have the cluster handy
        //
        socketsBufferSize =
          Const.toInt(
            originalTransformation.environmentSubstitute( clusterSchema.getSocketsBufferSize() ), 50000 );
        compressingSocketStreams = clusterSchema.isSocketsCompressed();

        // Validate the number of slaves. We need at least one to have a valid cluster
        //
        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(

View on GitHub (pinned to f3058517a1)