pentaho/pentaho-kettle · error · RuntimeException

A server socket allocation always has to accompanied by a…

Error message

A server socket allocation always has to accompanied by a cluster run ID but it was empty

What it means

TransformationMap.allocateServerSocketPort validates its inputs first and throws RuntimeException when clusteredRunId is empty, because every clustered server-socket allocation must be tagged with the cluster run ID used to route data between slave servers. It is a programming/configuration contract violation, not a runtime network failure.

Solutions

Ensure the caller generates/propagates a non-empty clusteredRunId (typically a GUID created when the clustered run is planned) before allocating ports.
If calling programmatically, pass the run ID from TransExecutionConfiguration / cluster run context instead of an empty string.
Check for version mismatches between Pentaho/Kettle clients and the Carte server that omit the run ID field.
Fix upstream code that resets or overwrites the clusteredRunId variable before allocation.

Example fix

// before
transMap.allocateServerSocketPort("", transName, srcSlave, srcStep, "0", tgtSlave, tgtStep, "0");

// after
String clusteredRunId = UUID.randomUUID().toString();
transMap.allocateServerSocketPort(clusteredRunId, transName, srcSlave, srcStep, "0", tgtSlave, tgtStep, "0");

Defensive patterns

Strategy: validation

Validate before calling

if (clusteredRunId == null || clusteredRunId.isEmpty())
  throw new IllegalStateException("generate a cluster run ID before allocating server sockets");

Try / catch

try {
  transMap.allocateServerSocketPort(clusteredRunId, ...);
} catch (RuntimeException e) {
  if (e.getMessage().contains("cluster run ID")) {
    throw new ConfigurationException("clustered run was planned without a run ID; check cluster setup code", e);
  }
  throw e;
}

Prevention

Always plan clustered executions through the standard TransExecutionConfiguration path, which generates run IDs.
Never pass empty strings for run identifiers in cluster port allocation calls.
Keep Kettle client and Carte server versions aligned.

When it happens

Trigger: testServerSocketPort or the clustered-transformation setup path invoking allocateServerSocketPort with an empty clusteredRunId — e.g. a TransHopMeta/cluster schema assembled programmatically without generating the run ID, or a caller constructing the clustered plan manually.

Common situations: Custom code or plugins building cluster-slice transformations without setting the clustered run ID; older/patched clients calling the Carte API with incomplete parameters; refactored code dropping the runId argument.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/www/TransformationMap.java:160

   * @param portRangeStart
   *          the start of the port range as described in the used cluster schema
   * @param hostname
   *          the host name to allocate this address for
   * @param clusteredRunId
   *          A unique id, created for each new clustered run during transformation split.
   * @param transformationName
   * @param sourceStepName
   * @param sourceStepCopy
   * @return
   */
  public SocketPortAllocation allocateServerSocketPort( int portRangeStart, String hostname,
    String clusteredRunId, String transformationName, String sourceSlaveName, String sourceStepName,
    String sourceStepCopy, String targetSlaveName, String targetStepName, String targetStepCopy ) {

    // Do some validations first...
    //
    if ( Utils.isEmpty( clusteredRunId ) ) {
      throw new RuntimeException(
        "A server socket allocation always has to accompanied by a cluster run ID but it was empty" );
    }
    if ( portRangeStart <= 0 ) {
      throw new RuntimeException(
        "A server socket allocation always has to accompanied by port range start > 0 but it was "
          + portRangeStart );
    }
    if ( Utils.isEmpty( hostname ) ) {
      throw new RuntimeException(
        "A server socket allocation always has to accompanied by a hostname but it was empty" );
    }
    if ( Utils.isEmpty( transformationName ) ) {
      throw new RuntimeException(
        "A server socket allocation always has to accompanied by a transformation name but it was empty" );
    }
    if ( Utils.isEmpty( sourceSlaveName ) ) {
      throw new RuntimeException(
        "A server socket allocation always has to accompanied by a source slave server name but it was empty" );

View on GitHub (pinned to f3058517a1)