pentaho/pentaho-kettle · error · KettleException

Unsupported situation detected where a remote input step is…

Error message

Unsupported situation detected where a remote input step is expecting data to end up in a particular Mapping Input step of a sub-transformation.  To solve it, insert a dummy step before the mapping.

What it means

In Mapping.processRow, remote input steps (clustered/remote execution sources) are attached to mappingInputs[0].getRemoteInputSteps(). If the sub-transformation has more than one Mapping Input, the code cannot decide which one should receive the remote step and throws this KettleException. It exists to force a single, unambiguous target for remote data delivery.

Solutions

Insert a Dummy step before the Mapping step in the parent transformation to disambiguate, per the message.
Reduce the sub-transformation to exactly one Mapping Input step.
If clustered, verify the sub-transformation's step copy/cluster schema settings so remote steps map to a single Mapping Input.
Run locally first to confirm the topology, then fix wiring before redeploying to the cluster.

Example fix

// before (clustered run)
ParentStep =====> Mapping(sub.ktr)  // sub.ktr: 2x MappingInput, remote steps unresolvable
// after
ParentStep =====> Dummy =====> Mapping(sub.ktr)  // or single MappingInput in sub.ktr

Defensive patterns

Strategy: validation

Validate before calling

// Before clustered execution, assert single Mapping Input in the sub-transformation:
long mappingInputs = subTransMeta.getSteps().stream()
  .filter(s -> s.getStepMeta() instanceof MappingInputMeta).count();
if (mappingInputs > 1) throw new IllegalStateException("Remote execution requires exactly one Mapping Input");

Try / catch

try {
  trans.execute(new String[0]); // clustered run
} catch (KettleException e) {
  if (e.getMessage().contains("remote input step")) {
    log.error("Remote input cannot target multiple Mapping Inputs: add Dummy step or reduce to one", e);
  } else { throw e; }
}

Prevention

Audit sub-transformations for multiple Mapping Inputs before enabling clustering.
Verify cluster schema and step copy settings on all environments.
Smoke-test the topology locally before cluster deployment.
Add Dummy steps to disambiguate any parent-to-mapping hop.

When it happens

Trigger: Running (often clustered/remote) a transformation where the Mapping step's sub-transformation contains multiple Mapping Input steps, and a remote input step's data must land in one specific Mapping Input — during remote-input wiring in processRow.

Common situations: Executing the transformation on a cluster (remote slave steps) where the sub-transf was designed with several Mapping Inputs; partitioned/clustered runs picking up a sub-transf originally used only locally.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/mapping/Mapping.java:127

            // over remotely to this mapping.
            // However, the data needs to end up at a Mapping Input step of the
            // sub-transformation, not in this step.
            // We can move over the remote steps to the Mapping Input step as long
            // as the threads haven't started yet.
            //
            for ( RemoteStep remoteStep : getRemoteInputSteps() ) {
              // Pass this rowset down to a mapping input step in the
              // sub-transformation...
              //
              if ( mappingInputs.length == 1 ) {
                // Simple case: only one input mapping. Move the remote step over
                //
                mappingInputs[0].getRemoteInputSteps().add( remoteStep );
              } else {
                // TODO: figure out where this remote step needs to go and where
                // it comes from.
                //
                throw new KettleException(
                    "Unsupported situation detected where a remote input step is expecting data "
                        + "to end up in a particular Mapping Input step of a sub-transformation.  "
                        + "To solve it, insert a dummy step before the mapping." );
              }
            }
            getRemoteInputSteps().clear();
          }

          // Do the same thing for output row sets
          //
          List<RowSet> outputRowSets = getOutputRowSets();
          if ( !outputRowSets.isEmpty() ) {
            for ( RowSet rowSet : outputRowSets ) {
              // Pass this rowset down to a mapping input step in the
              // sub-transformation...
              //
              if ( mappingOutputs.length == 1 ) {
                // Simple case: only one output mapping. Move the RowSet over

View on GitHub (pinned to f3058517a1)