{"record":{"id":"ea36eacd2848d815","repo":"pentaho/pentaho-kettle","slug":"the-transformation-needs-a-name-to-uniquely-identify-it-by","errorCode":null,"errorMessage":"The transformation needs a name to uniquely identify it by on the remote server.","messagePattern":"The transformation needs a name to uniquely identify it by on the remote server\\.","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/Trans.java","lineNumber":3746,"sourceCode":"   */\n  public void setRunning( boolean running ) {\n    status.updateAndGet( v -> running ? v | RUNNING.mask : ( BIT_STATUS_SUM ^ RUNNING.mask ) & v );\n  }\n\n  /**\n   * Execute the transformation in a clustered fashion. The transformation steps are split and collected in a\n   * TransSplitter object\n   *\n   * @param transMeta              the transformation's meta-data\n   * @param executionConfiguration the execution configuration\n   * @return the transformation splitter object\n   * @throws KettleException the kettle exception\n   */\n  public static TransSplitter executeClustered( final TransMeta transMeta,\n                                                final TransExecutionConfiguration executionConfiguration )\n    throws KettleException {\n    if ( Utils.isEmpty( transMeta.getName() ) ) {\n      throw new KettleException( \"The transformation needs a name to uniquely identify it by on the remote server.\" );\n    }\n\n    TransSplitter transSplitter = new TransSplitter( transMeta );\n    transSplitter.splitOriginalTransformation();\n\n    // Pass the clustered run ID to allow for parallel execution of clustered transformations\n    //\n    executionConfiguration.getVariables().put( Const.INTERNAL_VARIABLE_CLUSTER_RUN_ID, transSplitter\n      .getClusteredRunId() );\n\n    executeClustered( transSplitter, executionConfiguration );\n    return transSplitter;\n  }\n\n  /**\n   * Executes an existing TransSplitter, with the transformation already split.\n   *\n   * @param transSplitter          the trans splitter","sourceCodeStart":3728,"sourceCodeEnd":3764,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/Trans.java#L3728-L3764","documentation":"Trans.executeClustered() requires the transformation name to identify each clustered slave slice on the remote Carte servers. If transMeta.getName() is empty or null, it throws immediately before splitting.","triggerScenarios":"Calling Trans.executeClustered(transMeta, executionConfiguration) with an unsaved or programmatically built transformation whose name was never set.","commonSituations":"Building TransMeta in code and forgetting setName(), running a clustered execution from a temporary/unnamed transformation, or a file loaded without its name being populated.","solutions":["Call transMeta.setName(\"unique-name\") before executeClustered","Save the transformation with a name (if from a repository, ensure the repository object has a name)","Validate before cluster execution: if (Utils.isEmpty(transMeta.getName())) throw or set a default"],"exampleFix":"// before\nTransMeta meta = new TransMeta(\"/path/t.ktr\"); // unnamed\nTransSplitter s = Trans.executeClustered(meta, config);\n// after\nmeta.setName(\"my-clustered-trans\");\nTransSplitter s = Trans.executeClustered(meta, config);","handlingStrategy":"validation","validationCode":"if (Utils.isEmpty(transMeta.getName())) {\n  transMeta.setName(\"clustered-trans-\" + System.currentTimeMillis());\n}\nTransSplitter splitter = Trans.executeClustered(transMeta, config);","typeGuard":"boolean hasName(TransMeta m) { return m.getName() != null && !m.getName().trim().isEmpty(); }","tryCatchPattern":null,"preventionTips":["Always setName() on programmatically built TransMeta objects before clustered runs","Use unique, descriptive transformation names — they identify slices on Carte servers","Validate name before clustering in wrapper utility code","Don't rely on filename-derived names when loading from raw files"],"tags":["cluster","validation","naming"],"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"}