pentaho/pentaho-kettle · error · RuntimeException

A server socket allocation always has to accompanied by…

Error message

A server socket allocation always has to accompanied by port range start > 0 but it was " + portRangeStart

What it means

allocateServerSocketPort also validates portRangeStart and throws RuntimeException when it is <= 0, echoing the supplied value. The port range start defines where Carte begins searching for free ports for the clustered data channel; a zero/negative value is meaningless and indicates a broken cluster schema configuration.

Solutions

  1. Open the transformation's cluster schema in Spoon and set a valid Ports range (e.g. 40000) in the 'Sockets/Ports' field.
  2. Fix the port value in the ktr/kjb XML or carte config if edited by hand: ports must be a positive integer.
  3. When calling the API directly, pass a portRangeStart > 0 (the conventional default is 40000).
  4. Validate cluster schema settings before executing clustered transformations.

Example fix

// before: cluster schema XML with bad ports
<ports>0</ports>

// after
<ports>40000</ports>
Defensive patterns

Strategy: validation

Validate before calling

if (portRangeStart <= 0)
  throw new IllegalStateException("cluster schema ports must be a positive integer, got " + portRangeStart);
if (portRangeStart < 1024 || portRangeStart > 65535)
  log.warn("portRangeStart outside typical TCP range");

Prevention

When it happens

Trigger: testServerSocketPort or allocateServerSocketPort called with portRangeStart <= 0 — typically a cluster schema saved with empty/0 ports field, or programmatic callers passing 0 to mean 'default'.

Common situations: Cluster schema in the transformation left with the 'Ports' field blank or 0; config XML migrated between Kettle versions losing the ports attribute; hand-edited transformation XML (ktr) with a bad ports value.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of pentaho/pentaho-kettle@f3058517a1 (2026-09-13). Data as JSON: /api/errors/8c5017917edc6736. Report an issue: GitHub.

Appendix: source

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

   * @param clusteredRunId
   *          A unique id, created for each new clustered run during transformation split.
   * @param transformationName
   * @param sourceStepName
   * @param sourceStepCopy
   * @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" );

View on GitHub (pinned to f3058517a1)