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 target slave server name but it was empty

What it means

Thrown by TransformationMap.allocateServerSocketPort when targetSlaveName is empty. The allocation must know which slave receives the data so the port can be linked from source slave to target slave in the socket repository. The check runs before any port is reserved.

Solutions

  1. Add the target SlaveServer to the cluster schema and ensure the hop references it
  2. Pass the correct target slave name to allocateServerSocketPort
  3. Validate with Utils.isEmpty( targetSlaveName ) before the call

Example fix

// before
map.allocateServerSocketPort( 40000, host, trans, src, null, "stepA", "stepB", "0", "0" );
// after
map.allocateServerSocketPort( 40000, host, trans, src, targetSlave.getName(), "stepA", "stepB", "0", "0" );
Defensive patterns

Strategy: validation

Validate before calling

if ( Utils.isEmpty( targetSlaveName ) ) {
  throw new IllegalArgumentException( "target slave name required" );
}

Type guard

boolean hasSlave(String s) { return s != null && !s.trim().isEmpty(); }

Try / catch

try {
  map.allocateServerSocketPort( port, host, trans, src, tgtSlave, stepA, stepB, c1, c2 );
} catch ( RuntimeException e ) {
  if ( e.getMessage().contains( "target slave" ) ) {
    // add the target slave to the cluster schema
  }
}

Prevention

When it happens

Trigger: Calling allocateServerSocketPort with targetSlaveName=null or ""; cluster schema missing the target (receiving) slave server for the hop being clustered.

Common situations: Incomplete master-to-slave cluster definition; target slave removed from cluster schema but hops still reference it; programmatic cluster config that only sets the source slave.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

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

    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" );
    }
    if ( Utils.isEmpty( targetSlaveName ) ) {
      throw new RuntimeException(
        "A server socket allocation always has to accompanied by a target slave server name but it was empty" );
    }
    if ( Utils.isEmpty( sourceStepName ) ) {
      throw new RuntimeException(
        "A server socket allocation always has to accompanied by a source step name but it was empty" );
    }
    if ( Utils.isEmpty( targetStepName ) ) {
      throw new RuntimeException(
        "A server socket allocation always has to accompanied by a target step name but it was empty" );
    }
    if ( Utils.isEmpty( sourceStepCopy ) ) {
      throw new RuntimeException(
        "A server socket allocation always has to accompanied by a source step copy but it was empty" );
    }
    if ( Utils.isEmpty( targetStepCopy ) ) {
      throw new RuntimeException(
        "A server socket allocation always has to accompanied by a target step copy but it was empty" );
    }

View on GitHub (pinned to f3058517a1)