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

What it means

Thrown by TransformationMap.allocateServerSocketPort when the transformationName argument is empty. Each allocated server socket is keyed by the transformation that owns it, so an empty name would create an untraceable port allocation. The check runs before any port reservation on the slave host.

Solutions

Set a valid name on the TransMeta / transformation being clustered before registration
Guard with Utils.isEmpty( transformationName ) in caller code before invoking the API
Fix the .ktr/source so the transformation has a name

Example fix

// before
map.allocateServerSocketPort( 40000, host, null, "src", "tgt", "stepA", "stepB", "0", "0" );
// after
String name = transMeta.getName();
if ( Utils.isEmpty( name ) ) throw new IllegalArgumentException( "transformation must have a name" );
map.allocateServerSocketPort( 40000, host, name, "src", "tgt", "stepA", "stepB", "0", "0" );

Defensive patterns

Strategy: validation

Validate before calling

if ( Utils.isEmpty( transMeta.getName() ) ) {
  throw new IllegalArgumentException( "transformation must be named before clustering" );
}

Type guard

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

Try / catch

try {
  map.allocateServerSocketPort( port, host, name, src, tgt, stepA, stepB, c1, c2 );
} catch ( RuntimeException e ) {
  if ( e.getMessage().contains( "transformation name" ) ) {
    // name the transformation and retry
  }
}

Prevention

Never execute clustered transformations that have not been saved with a name
Validate TransMeta name as part of pre-execution checks
Avoid renaming steps/transformations late in the pipeline design

When it happens

Trigger: Calling allocateServerSocketPort with transformationName=null or "" while hostname passes validation.

Common situations: Registering a clustered transformation whose transformation meta has no name (unnamed or corrupt .ktr); building the registration call programmatically and skipping setName; XML round-trip losing the name attribute.

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

Appendix: source

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

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

View on GitHub (pinned to f3058517a1)