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

What it means

Thrown by TransformationMap.allocateServerSocketPort when sourceStepCopy is empty. In clustered transformations a step can run in multiple copies; the copy number ('0', '1', ...) disambiguates which copy owns the socket. Empty copy strings would make the allocation ambiguous, so it is rejected.

Solutions

  1. Generate proper partition/copy numbering (e.g. "0") for the clustered source step before registration
  2. Pass the source step's copy string to allocateServerSocketPort
  3. Validate with Utils.isEmpty( sourceStepCopy ) 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", sourceCopyNr, "0" );
Defensive patterns

Strategy: validation

Validate before calling

if ( Utils.isEmpty( sourceStepCopy ) ) {
  throw new IllegalArgumentException( "source 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( "source step copy" ) ) {
    // regenerate partition/copy numbering
  }
}

Prevention

When it happens

Trigger: Calling allocateServerSocketPort with sourceStepCopy=null or ""; partitioned/serviced cluster steps whose copy numbering was not generated.

Common situations: Partitioning schema applied without generating copies; programmatic cluster registration hardcoding copies incorrectly; legacy transformations predating copy-aware clustering.

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

Appendix: source

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

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

View on GitHub (pinned to f3058517a1)