pentaho/pentaho-kettle · error · KettleException

MappingOutput.Exception.UnableToConnectWithParentMapping

MappingOutput.Exception.UnableToConnectWithParentMapping

Error message

MappingOutput.Exception.UnableToConnectWithParentMapping

What it means

MappingOutput.processRow() waits for the parent mapping (Mapping sub-transformation) to wire up its input rowsets. If no connection from the parent's MappingInput arrives within 60 seconds (totalsleep > 60000, polled in 10ms sleeps), it throws this KettleException naming how many seconds elapsed. It means the sub-transformation never received data/configuration from its parent mapping step.

Solutions

Run the sub-transformation only via a parent transformation containing a 'Mapping' step — never standalone.
Verify the parent's Mapping step is correctly wired: MappingInput of parent connects to the sub-transformation's entry point.
Check that the parent transformation actually starts and initializes all steps (look for parent-side initialization errors in logs).
If the parent legitimately starts late, restructure so the mapping input is available sooner, or reduce unnecessary delays in the parent.

Example fix

// before: executing sub-transformation directly
Trans subTrans = new Trans(subTransMeta);
subTrans.execute(null);

// after: run it through the parent mapping
Trans parentTrans = new Trans(parentTransMeta);
parentTrans.execute(null); // Mapping step initializes and feeds the sub-transformation
parentTrans.waitUntilFinished();

Defensive patterns

Strategy: validation

Validate before calling

// before running the sub-transformation, confirm it is invoked via a Mapping step
boolean runViaMapping = transMeta.findMappingStepName() != null; // in parent context
// or verify parent hop wiring in Spoon:// Mapping step's input mapping must map to this MappingOutput step

Try / catch

try {
  processRowLogic();
} catch (KettleException e) {
  if (e.getMessage().contains("UnableToConnectWithParentMapping")) {
    logError("MappingOutput never received configuration from parent MappingInput; check parent transformation wiring", e);
  }
  setErrors(1);
  stopAll();
}

Prevention

Never execute mapping sub-transformation files standalone in production.
After renaming steps inside a mapping, re-verify the parent Mapping step's field mappings.
Ensure the parent transformation completes initialization before depending on mapping output.
Watch Spoon warnings about unconnected mapping input/output steps.

When it happens

Trigger: Running a mapping sub-transformation whose MappingOutput step never gets connected by the parent's MappingInput — parent transformation not started, MappingInput/MappingOutput wiring removed, or the parent thread died before sending row metadata.

Common situations: Executing the sub-transformation standalone (debugging) instead of through a Mapping step; parent transformation aborted early; step name mismatches after renaming steps inside the mapping; deadlocked parent that never initializes its mapping children.

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/mappingoutput/MappingOutput.java:83

      meta.setInputValueRenames( data.inputValueRenames );
      meta.getFields( getTransMeta().getBowl(), data.outputRowMeta, getStepname(), null, null, this, repository,
        metaStore );

      //
      // Wait until the parent transformation has started completely.
      // However, don't wait forever, if we don't have a connection after 60 seconds: bail out!
      //
      int totalsleep = 0;
      if ( getTrans().getParentTrans() != null ) {
        while ( !isStopped() && !getTrans().getParentTrans().isRunning() ) {
          try {
            totalsleep += 10;
            Thread.sleep( 10 );
          } catch ( InterruptedException e ) {
            stopAll();
          }
          if ( totalsleep > 60000 ) {
            throw new KettleException( BaseMessages.getString(
              PKG, "MappingOutput.Exception.UnableToConnectWithParentMapping", "" + ( totalsleep / 1000 ) ) );
          }
        }
      }
      // Now see if there is a target step to send data to.
      // If not, simply eat the data...
      //
      if ( data.targetSteps == null ) {
        logDetailed( BaseMessages.getString( PKG, "MappingOutput.NoTargetStepSpecified", getStepname() ) );
      }
    }

    // Copy row to possible alternate rowset(s).
    // Rowsets where added for all the possible targets in the setter for data.targetSteps...
    //
    putRow( data.outputRowMeta, r );

    if ( checkFeedback( getLinesRead() ) ) {

View on GitHub (pinned to f3058517a1)