pentaho/pentaho-kettle · error · KettleException

MappingInput.Exception.UnableToConnectWithParentMapping

MappingInput.Exception.UnableToConnectWithParentMapping

Error message

Unable to connect with parent transformation after {0} seconds.

What it means

The Mapping Input step (the entry point of a sub-transformation used inside a Mapping step) waits up to `timeOut` milliseconds (default 60s) for the parent transformation to wire up its source steps via setConnectorSteps. If `data.sourceSteps` is still null after the timeout, it throws this KettleException. It means the parent Mapping transformation never connected the sub-transformation, typically because mapping execution was not prepared correctly or the parent died before wiring.

Solutions

Verify the Mapping step references a valid sub-transformation and that the parent transformation initializes it (prepareMappingExecution is called) before rows flow.
Check that the sub-transformation contains a Mapping Input step whose step name matches the mapping stepname passed to setConnectorSteps.
Increase the timeout via MappingInput.setTimeOut() if startup is legitimately slow.
Inspect parent transformation logs for earlier failures that prevented connector wiring.
Ensure you are not launching the sub-transformation directly instead of through a Mapping step.

Example fix

// before: launching sub-trans directly, no mapping wiring
Trans subTrans = new Trans(subTransMeta);
subTrans.execute(null);
// after: use Mapping step / ensure parent prepares mapping execution
MappingMeta mappingMeta = ...; // Mapping step in parent references subTransMeta
parentTrans.prepareExecution(new Object[0]);
parentTrans.startThreads();

Defensive patterns

Strategy: validation

Validate before calling

// Before running: confirm the sub-transformation has a Mapping Input step and the parent Mapping step points at it
MappingInputMeta input = (MappingInputMeta) subTransMeta.findMappingInputStep();
if (input == null) throw new IllegalStateException("Sub-transformation lacks a Mapping Input step");
TransMeta parent = mappingStepMeta.getParentTransMeta();
if (parent.findMappingInputStep() == null) throw new IllegalStateException("Mapping step not wired to sub-transformation");

Type guard

boolean isWired(MappingInputData data) { return data != null && data.sourceSteps != null; }

Try / catch

try {
  trans.prepareExecution(new Object[0]);
  trans.startThreads();
  trans.waitUntilFinished();
} catch (KettleException e) {
  if (e.getMessage().contains("Unable to connect with parent transformation")) {
    // mapping not wired: check Mapping step config and prepareMappingExecution
  }
  throw e;
}

Prevention

Always launch mappings through a Mapping step / prepareMappingExecution, never execute the sub-transformation directly.
Verify the Mapping Input step name matches the mappingStepname passed in setConnectorSteps.
Call setTimeOut() for slow-starting environments.
Check parent transformation logs for wiring failures before rows start.

When it happens

Trigger: processRow() spins while `data.sourceSteps == null`; if setConnectorSteps() is never invoked by the parent's prepareMappingExecution within the timeout (60s by default, configurable via setTimeOut), this exception is thrown.

Common situations: Running a transformation that uses a Mapping (sub-transformation) step where the sub-transformation is misconfigured; programmatic use of Trans/Mapping APIs where prepareMappingExecution/setConnectorSteps is skipped; a hung or failed parent transformation; extremely slow environment startup exceeding the 60s window.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/mappinginput/MappingInput.java:80

  public boolean processRow( StepMetaInterface smi, StepDataInterface sdi ) throws KettleException {
    meta = (MappingInputMeta) smi;
    data = (MappingInputData) sdi;

    if ( !data.linked ) {
      //
      // Wait until we know were to read from the parent transformation...
      // However, don't wait forever, if we don't have a connection after 60 seconds: bail out!
      //
      int totalsleep = 0;
      while ( !isStopped() && data.sourceSteps == null ) {
        try {
          totalsleep += 10;
          Thread.sleep( 10 );
        } catch ( InterruptedException e ) {
          stopAll();
        }
        if ( totalsleep > timeOut ) {
          throw new KettleException( BaseMessages.getString( PKG,
              "MappingInput.Exception.UnableToConnectWithParentMapping", "" + ( totalsleep / 1000 ) ) );
        }
      }

      // OK, now we're ready to read from the parent source steps.
      data.linked = true;
    }

    Object[] row = getRow();
    if ( row == null ) {
      setOutputDone();
      return false;
    }

    if ( first ) {
      first = false;

      // The Input RowMetadata is not the same as the output row meta-data.

View on GitHub (pinned to f3058517a1)