{"record":{"id":"0a2bc41c52d7a352","repo":"pentaho/pentaho-kettle","slug":"a-server-socket-allocation-always-has-to-accompanied-by-a-0a2bc4","errorCode":null,"errorMessage":"A server socket allocation always has to accompanied by a hostname but it was empty","messagePattern":"A server socket allocation always has to accompanied by a hostname but it was empty","errorType":"validation","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/www/TransformationMap.java","lineNumber":169,"sourceCode":"   * @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\" );\n    }\n    if ( Utils.isEmpty( sourceStepName ) ) {\n      throw new RuntimeException(\n        \"A server socket allocation always has to accompanied by a source step name but it was empty\" );\n    }","sourceCodeStart":151,"sourceCodeEnd":187,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/www/TransformationMap.java#L151-L187","documentation":"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.","triggerScenarios":"Calling allocateServerSocketPort (directly or via the Carte web API /registerSlave or cluster socket registration endpoints) with hostname=null or \"\" while portRangeStart>0.","commonSituations":"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.","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"],"exampleFix":"// before\nmap.allocateServerSocketPort( 40000, null, \"trans1\", \"src\", \"tgt\", \"stepA\", \"stepB\", \"0\", \"0\" );\n// after\nif ( Utils.isEmpty( hostName ) ) throw new IllegalArgumentException( \"hostname required\" );\nmap.allocateServerSocketPort( 40000, hostName, \"trans1\", \"src\", \"tgt\", \"stepA\", \"stepB\", \"0\", \"0\" );","handlingStrategy":"validation","validationCode":"if ( Utils.isEmpty( hostName ) ) {\n  throw new IllegalArgumentException( \"hostname is required for server socket allocation\" );\n}","typeGuard":"boolean hasHostname(String s) { return s != null && !s.trim().isEmpty(); }","tryCatchPattern":"try {\n  map.allocateServerSocketPort( port, host, trans, src, tgt, stepA, stepB, c1, c2 );\n} catch ( RuntimeException e ) {\n  if ( e.getMessage().contains( \"hostname\" ) ) {\n    // fix slave server config and retry\n  }\n}","preventionTips":["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"],"tags":["java","kettle","carte","clustering"],"backgroundTag":"empty-required-field","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"}