pentaho/pentaho-kettle · error · KettleException

ClusterSchema.NoMasterServerDefined

Error message

ClusterSchema.NoMasterServerDefined

What it means

Thrown by ClusterSchema.findMaster when the cluster schema has slave servers defined but none of them is marked as master. A clustered transformation requires exactly one master slave server to coordinate execution.

Solutions

1. Open the cluster schema and mark one slave server as master (isMaster=true)
2. Verify via getSlaveServers() that at least one entry has master set before splitting a transformation
3. Re-create the cluster schema definition if it came from an older/round-tripped export

Example fix

// before: schema with only slaves
schema.getSlaveServers().forEach(s -> s.setMaster(false));
splitter.splitOriginalTransformation(transMeta);
// after: designate a master before splitting
boolean hasMaster = schema.getSlaveServers().stream().anyMatch(SlaveServer::isMaster);
if (!hasMaster && !schema.getSlaveServers().isEmpty()) { schema.getSlaveServers().get(0).setMaster(true); }
splitter.splitOriginalTransformation(transMeta);

// Before clustering, verify a master exists
boolean hasMaster = clusterSchema.getSlaveServers().stream().anyMatch(SlaveServer::isMaster);
if (!hasMaster) { throw new KettleException("Cluster schema '" + clusterSchema.getName() + "' has no master"); }

boolean isUsableClusterSchema(ClusterSchema s) { return s != null && !s.getSlaveServers().isEmpty() && s.getSlaveServers().stream().anyMatch(SlaveServer::isMaster); }

try { SlaveServer master = clusterSchema.findMaster(); }
catch (KettleException e) { // no master defined — fix schema in UI/metadata before retry
  throw new IllegalStateException("Configure a master in cluster schema", e); }

When it happens

Trigger: findMaster is called (e.g. by TransSplitter, getMasterServer, or cluster configuration check) while slaveServers is non-empty and no SlaveServer.isMaster() returns true.

Common situations: Cluster schema configured with slaves only and the master checkbox left unset; schema imported from XML or metadata where master flag was lost; master renamed without updating the cluster schema.

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

• At this time we don't support the use of multiple cluster…
• ClusterSchema.NoSlaveServerDefined
• It doesn't make sense to have a partitioned, clustered step…
• No master server could be found in the original…
• You always need at least one master in a cluster schema.

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/cluster/ClusterSchema.java:280

  }

  /**
   * @param basePort
   *          the basePort to set
   */
  public void setBasePort( String basePort ) {
    this.basePort = basePort;
  }

  public SlaveServer findMaster() throws KettleException {
    for ( int i = 0; i < slaveServers.size(); i++ ) {
      SlaveServer slaveServer = slaveServers.get( i );
      if ( slaveServer.isMaster() ) {
        return slaveServer;
      }
    }
    if ( slaveServers.size() > 0 ) {
      throw new KettleException( BaseMessages.getString( PKG, "ClusterSchema.NoMasterServerDefined", name ) );
    }
    throw new KettleException( BaseMessages.getString( PKG, "ClusterSchema.NoSlaveServerDefined", name ) );
  }

  /**
   * @return The number of slave servers, excluding the master server
   */
  public int findNrSlaves() {
    int nr = 0;
    for ( int i = 0; i < slaveServers.size(); i++ ) {
      SlaveServer slaveServer = slaveServers.get( i );
      if ( !slaveServer.isMaster() ) {
        nr++;
      }
    }
    return nr;
  }

View on GitHub (pinned to f3058517a1)