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 step name but it was empty

What it means

Thrown by TransformationMap.allocateServerSocketPort when targetStepName is empty. The receiving step name is required so the allocated port can be matched to the step that will open the server socket on the target slave. The check runs before any port is reserved.

Solutions

Ensure the clustered hop's target step exists and has a name
Pass the correct target step name to allocateServerSocketPort
Validate with Utils.isEmpty( targetStepName ) before the call

Example fix

// before
map.allocateServerSocketPort( 40000, host, trans, src, tgt, "stepA", "", "0", "0" );
// after
map.allocateServerSocketPort( 40000, host, trans, src, tgt, "stepA", targetStep.getName(), "0", "0" );

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

try {
  map.allocateServerSocketPort( port, host, trans, src, tgt, srcStep, tgtStep, c1, c2 );
} catch ( RuntimeException e ) {
  if ( e.getMessage().contains( "target step" ) ) {
    // repair hop target step reference
  }
}

Prevention

Validate all hop endpoints exist and are named before clustered execution
Re-check transformations after bulk renames
Run clustered smoke tests in CI

When it happens

Trigger: Calling allocateServerSocketPort with targetStepName=null or ""; clustered hop with a missing target step reference.

Common situations: Hop pointing at a deleted/renamed target step; generated cluster partitions missing step names; hand-rolled socket allocation calls.

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/04454110d4a8b39c. Report an issue: GitHub.

Appendix: source

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

    }
    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" );
    }

      // Look up the sockets list for the given host
      //
    List<SocketPortAllocation> serverSocketPorts;
    serverSocketPorts = hostServerSocketPortsMap.computeIfAbsent( hostname, k -> new CopyOnWriteArrayList<>() );
    serverSocketPorts = serverSocketPorts != null ? serverSocketPorts : hostServerSocketPortsMap.get( hostname );

        // Find the socket port allocation in the list...

View on GitHub (pinned to f3058517a1)