{"record":{"id":"8c5017917edc6736","repo":"pentaho/pentaho-kettle","slug":"a-server-socket-allocation-always-has-to-accompanied-by-port","errorCode":null,"errorMessage":"A server socket allocation always has to accompanied by port range start > 0 but it was \" + portRangeStart","messagePattern":"A server socket allocation always has to accompanied by port range start > 0 but it was \" \\+ portRangeStart","errorType":"validation","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/www/TransformationMap.java","lineNumber":164,"sourceCode":"   * @param clusteredRunId\n   *          A unique id, created for each new clustered run during transformation split.\n   * @param transformationName\n   * @param sourceStepName\n   * @param sourceStepCopy\n   * @return\n   */\n  public SocketPortAllocation allocateServerSocketPort( int portRangeStart, String hostname,\n    String clusteredRunId, String transformationName, String sourceSlaveName, String sourceStepName,\n    String sourceStepCopy, String targetSlaveName, String targetStepName, String targetStepCopy ) {\n\n    // Do some validations first...\n    //\n    if ( Utils.isEmpty( clusteredRunId ) ) {\n      throw new RuntimeException(\n        \"A server socket allocation always has to accompanied by a cluster run ID but it was empty\" );\n    }\n    if ( portRangeStart <= 0 ) {\n      throw new RuntimeException(\n        \"A server socket allocation always has to accompanied by port range start > 0 but it was \"\n          + portRangeStart );\n    }\n    if ( Utils.isEmpty( hostname ) ) {\n      throw new RuntimeException(\n        \"A server socket allocation always has to accompanied by a hostname but it was empty\" );\n    }\n    if ( Utils.isEmpty( transformationName ) ) {\n      throw new RuntimeException(\n        \"A server socket allocation always has to accompanied by a transformation name but it was empty\" );\n    }\n    if ( Utils.isEmpty( sourceSlaveName ) ) {\n      throw new RuntimeException(\n        \"A server socket allocation always has to accompanied by a source slave server name but it was empty\" );\n    }\n    if ( Utils.isEmpty( targetSlaveName ) ) {\n      throw new RuntimeException(\n        \"A server socket allocation always has to accompanied by a target slave server name but it was empty\" );","sourceCodeStart":146,"sourceCodeEnd":182,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/www/TransformationMap.java#L146-L182","documentation":"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.","triggerScenarios":"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'.","commonSituations":"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.","solutions":["Open the transformation's cluster schema in Spoon and set a valid Ports range (e.g. 40000) in the 'Sockets/Ports' field.","Fix the port value in the ktr/kjb XML or carte config if edited by hand: ports must be a positive integer.","When calling the API directly, pass a portRangeStart > 0 (the conventional default is 40000).","Validate cluster schema settings before executing clustered transformations."],"exampleFix":"// before: cluster schema XML with bad ports\n<ports>0</ports>\n\n// after\n<ports>40000</ports>","handlingStrategy":"validation","validationCode":"if (portRangeStart <= 0)\n  throw new IllegalStateException(\"cluster schema ports must be a positive integer, got \" + portRangeStart);\nif (portRangeStart < 1024 || portRangeStart > 65535)\n  log.warn(\"portRangeStart outside typical TCP range\");","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never leave the cluster schema Ports field blank or zero in Spoon.","Validate ktr/kjb XML after hand edits or version migrations.","Use the conventional default range (e.g. 40000+) when configuring cluster schemas."],"tags":["clustering","validation","port","carte","configuration"],"backgroundTag":"invalid-argument-value","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}