pentaho/pentaho-kettle · error · KettleException

The transformation needs a name to uniquely identify it by…

Error message

The transformation needs a name to uniquely identify it by on the remote server.

What it means

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.

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

Example fix

// before
TransMeta meta = new TransMeta("/path/t.ktr"); // unnamed
TransSplitter s = Trans.executeClustered(meta, config);
// after
meta.setName("my-clustered-trans");
TransSplitter s = Trans.executeClustered(meta, config);

Defensive patterns

Strategy: validation

Validate before calling

if (Utils.isEmpty(transMeta.getName())) {
  transMeta.setName("clustered-trans-" + System.currentTimeMillis());
}
TransSplitter splitter = Trans.executeClustered(transMeta, config);

Type guard

boolean hasName(TransMeta m) { return m.getName() != null && !m.getName().trim().isEmpty(); }

Prevention

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

When it happens

Trigger: Calling Trans.executeClustered(transMeta, executionConfiguration) with an unsaved or programmatically built transformation whose name was never set.

Common situations: 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.

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/Trans.java:3746

   */
  public void setRunning( boolean running ) {
    status.updateAndGet( v -> running ? v | RUNNING.mask : ( BIT_STATUS_SUM ^ RUNNING.mask ) & v );
  }

  /**
   * Execute the transformation in a clustered fashion. The transformation steps are split and collected in a
   * TransSplitter object
   *
   * @param transMeta              the transformation's meta-data
   * @param executionConfiguration the execution configuration
   * @return the transformation splitter object
   * @throws KettleException the kettle exception
   */
  public static TransSplitter executeClustered( final TransMeta transMeta,
                                                final TransExecutionConfiguration executionConfiguration )
    throws KettleException {
    if ( Utils.isEmpty( transMeta.getName() ) ) {
      throw new KettleException( "The transformation needs a name to uniquely identify it by on the remote server." );
    }

    TransSplitter transSplitter = new TransSplitter( transMeta );
    transSplitter.splitOriginalTransformation();

    // Pass the clustered run ID to allow for parallel execution of clustered transformations
    //
    executionConfiguration.getVariables().put( Const.INTERNAL_VARIABLE_CLUSTER_RUN_ID, transSplitter
      .getClusteredRunId() );

    executeClustered( transSplitter, executionConfiguration );
    return transSplitter;
  }

  /**
   * Executes an existing TransSplitter, with the transformation already split.
   *
   * @param transSplitter          the trans splitter

View on GitHub (pinned to f3058517a1)