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

What it means

Thrown by TransformationMap.allocateServerSocketPort when a clustered/slave server socket allocation is requested with an empty hostname. Carte requires every server-socket allocation to be fully identified (hostname, transformation, slaves, steps, copies) so the port can be registered against the correct host's socket list. The guard runs before any port is reserved.

Solutions

Set the hostname on the slave server definition (ClusterSlave/SlaveServer) before allocating the server socket
Validate hostName in your cluster setup code before calling allocateServerSocketPort
If driven by a Carte HTTP call, fix the client request so it includes the host parameter

Example fix

// before
map.allocateServerSocketPort( 40000, null, "trans1", "src", "tgt", "stepA", "stepB", "0", "0" );
// after
if ( Utils.isEmpty( hostName ) ) throw new IllegalArgumentException( "hostname required" );
map.allocateServerSocketPort( 40000, hostName, "trans1", "src", "tgt", "stepA", "stepB", "0", "0" );

Defensive patterns

Strategy: validation

Validate before calling

if ( Utils.isEmpty( hostName ) ) {
  throw new IllegalArgumentException( "hostname is required for server socket allocation" );
}

Type guard

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

Try / catch

try {
  map.allocateServerSocketPort( port, host, trans, src, tgt, stepA, stepB, c1, c2 );
} catch ( RuntimeException e ) {
  if ( e.getMessage().contains( "hostname" ) ) {
    // fix slave server config and retry
  }
}

Prevention

Always define hostname on every SlaveServer in cluster schemas
Validate cluster metadata before clustered execution
Prefer loading cluster definitions from reviewed XML rather than hand-building them

When it happens

Trigger: Calling allocateServerSocketPort (directly or via the Carte web API /registerSlave or cluster socket registration endpoints) with hostname=null or "" while portRangeStart>0.

Common situations: Clustered transformation misconfiguration: the slave server entry in the cluster schema has no hostname; programmatically building a TransExecutionConfiguration or SocketRepository allocation and forgetting to set the host; XML/meta deserialization leaving hostname blank.

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

Appendix: source

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

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

View on GitHub (pinned to f3058517a1)