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

What it means

Thrown by TransformationMap.allocateServerSocketPort when targetStepCopy is empty. Like the source copy, the target step's copy number is required to fully identify the server socket on the receiving slave. This is the last validation before the method proceeds to look up the host's socket port list.

Solutions

  1. Generate the target step copy number (e.g. "0") before clustered registration
  2. Pass the target step's copy string to allocateServerSocketPort
  3. Validate with Utils.isEmpty( targetStepCopy ) before the call

Example fix

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

Strategy: validation

Validate before calling

if ( Utils.isEmpty( targetStepCopy ) ) {
  throw new IllegalArgumentException( "target step copy number required" );
}

Type guard

boolean hasCopy(String s) { return s != null && s.matches( "\\d+" ); }

Try / catch

try {
  map.allocateServerSocketPort( port, host, trans, src, tgt, stepA, stepB, srcCopy, tgtCopy );
} catch ( RuntimeException e ) {
  if ( e.getMessage().contains( "target step copy" ) ) {
    // regenerate target step copy numbering
  }
}

Prevention

When it happens

Trigger: Calling allocateServerSocketPort with targetStepCopy=null or ""; missing copy generation for the clustered target step.

Common situations: Partitioned cluster steps without generated copy numbers; programmatic registration omitting copy arguments; transformations edited externally so copy metadata was lost.

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

Appendix: source

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

    }
    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...
        //
    SocketPortAllocation socketPortAllocation = null;
    int maxPort = portRangeStart - 1;
    for ( int index = 0; index < serverSocketPorts.size(); index++ ) {
      SocketPortAllocation spa = serverSocketPorts.get( index );
      if ( spa.getPort() > maxPort ) {
        maxPort = spa.getPort();
      }

View on GitHub (pinned to f3058517a1)