What causes "There was an error during transformation split" in pentaho/pentaho-kettle?

Inspect the cause (getCause()) of this exception; the real problem is the wrapped exception.

pentaho/pentaho-kettle · error · KettleException

There was an error during transformation split

Error message

There was an error during transformation split

What it means

Catch-all wrapper in Trans.prepareExecution(String[]) for the clustered transformation split/prepare/start flow: any non-KettleException thrown while splitting the transformation across the cluster or talking to slaves is rethrown as this KettleException with the original as cause.

Solutions

Inspect the cause (getCause()) of this exception; the real problem is the wrapped exception.
Verify every slave server in the cluster schema is defined, non-null, and resolvable by hostname.
Check that slave responses are genuine Carte XML WebResults and not intercepted by a proxy or auth page.
Test the cluster schema with a trivial transformation to isolate split-specific issues.
Ensure the transformation itself serializes cleanly (valid step metadata, no broken plugin steps).

Example fix

// before: slave hostname typo causes generic split error
slaveServer.setHostname("slvae1");
// after
class.ClusterSchema cs = transMeta.findClusterSchema("my-cluster");
for (SlaveServer s : cs.getSlaveServers()) {
  InetAddress.getByName(s.getHostname()); // fails fast with a clear cause
}

Defensive patterns

Strategy: try-catch

Validate before calling

// fail fast on unresolved hostnames and null slaves before splitting
for (SlaveServer s : transMeta.findClusterSchema(name).getSlaveServers()) {
  Objects.requireNonNull(s, "null slave server in schema");
  InetAddress.getByName(s.getHostname());
}

Try / catch

try {
  trans.prepareExecution(new String[0]);
} catch (KettleException e) {
  if (e.getMessage().contains("error during transformation split")) {
    Throwable root = e;
    while (root.getCause() != null) root = root.getCause();
    log.error("Split root cause: " + root, root);
  } else throw e;
}

Prevention

Unwrap and log getCause() chain to find the real failure.
Validate every slave server entry (host, port, credentials) before running.
Ensure no proxy intercepts Carte HTTP responses with HTML.
Prove the transformation serializes cleanly by round-tripping TransMeta XML locally.

When it happens

Trigger: Any unexpected Exception during Trans.splitOriginalTransformation or the prepare/start servlet loop on a clustered transformation: URLEncoder failure, XML parse of a slave reply, NPE from a null slave/carte object id, or IO problem inside execService surfaced as a generic exception.

Common situations: Malformed/non-XML response from a slave (proxy error page, HTML login page); null slave server in cluster schema; serialization failure of TransMeta during split; DNS resolution problems surfacing as raw IOException.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

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

Appendix: source

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

          // WG: Should these be threaded like the above initialization?
          for ( int i = 0; i < slaves.length; i++ ) {
            TransMeta slaveTrans = transSplitter.getSlaveTransMap().get( slaves[ i ] );
            String carteObjectId = carteObjectMap.get( slaveTrans );
            String slaveReply =
              slaves[ i ].execService( StartExecutionTransServlet.CONTEXT_PATH + "/?name=" + URLEncoder.encode(
                slaveTrans.getName(), "UTF-8" ) + "&id=" + URLEncoder.encode( carteObjectId, "UTF-8" ) + "&xml=Y" );
            WebResult webResult = WebResult.fromXMLString( slaveReply );
            if ( !webResult.getResult().equalsIgnoreCase( WebResult.STRING_OK ) ) {
              throw new KettleException( "An error occurred while starting the execution of a slave transformation: "
                + webResult.getMessage() );
            }
          }
        }
      }
    } catch ( KettleException ke ) {
      throw ke;
    } catch ( Exception e ) {
      throw new KettleException( "There was an error during transformation split", e );
    }
  }

  /**
   * Monitors a clustered transformation every second, after all the transformations in a cluster schema are running.
   * <br>
   * Now we should verify that they are all running as they should.<br>
   * If a transformation has an error, we should kill them all.<br>
   * This should happen in a separate thread to prevent blocking of the UI.<br>
   * <br>
   * When the master and slave transformations have all finished, we should also run<br>
   * a cleanup on those transformations to release sockets, etc.<br>
   * <br>
   *
   * @param log           the log interface channel
   * @param transSplitter the transformation splitter object
   * @param parentJob     the parent job when executed in a job, otherwise just set to null
   * @return the number of errors encountered

View on GitHub (pinned to f3058517a1)