{"record":{"id":"4020569fc106baa8","repo":"pentaho/pentaho-kettle","slug":"mappinginput-exception-unabletoconnectwithparentmapping","errorCode":"MappingInput.Exception.UnableToConnectWithParentMapping","errorMessage":"Unable to connect with parent transformation after {0} seconds.","messagePattern":"Unable to connect with parent transformation after (.+?) seconds\\.","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/mappinginput/MappingInput.java","lineNumber":80,"sourceCode":"  public boolean processRow( StepMetaInterface smi, StepDataInterface sdi ) throws KettleException {\n    meta = (MappingInputMeta) smi;\n    data = (MappingInputData) sdi;\n\n    if ( !data.linked ) {\n      //\n      // Wait until we know were to read from the parent transformation...\n      // However, don't wait forever, if we don't have a connection after 60 seconds: bail out!\n      //\n      int totalsleep = 0;\n      while ( !isStopped() && data.sourceSteps == null ) {\n        try {\n          totalsleep += 10;\n          Thread.sleep( 10 );\n        } catch ( InterruptedException e ) {\n          stopAll();\n        }\n        if ( totalsleep > timeOut ) {\n          throw new KettleException( BaseMessages.getString( PKG,\n              \"MappingInput.Exception.UnableToConnectWithParentMapping\", \"\" + ( totalsleep / 1000 ) ) );\n        }\n      }\n\n      // OK, now we're ready to read from the parent source steps.\n      data.linked = true;\n    }\n\n    Object[] row = getRow();\n    if ( row == null ) {\n      setOutputDone();\n      return false;\n    }\n\n    if ( first ) {\n      first = false;\n\n      // The Input RowMetadata is not the same as the output row meta-data.","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/mappinginput/MappingInput.java#L62-L98","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before: launching sub-trans directly, no mapping wiring\nTrans subTrans = new Trans(subTransMeta);\nsubTrans.execute(null);\n// after: use Mapping step / ensure parent prepares mapping execution\nMappingMeta mappingMeta = ...; // Mapping step in parent references subTransMeta\nparentTrans.prepareExecution(new Object[0]);\nparentTrans.startThreads();","handlingStrategy":"validation","validationCode":"// Before running: confirm the sub-transformation has a Mapping Input step and the parent Mapping step points at it\nMappingInputMeta input = (MappingInputMeta) subTransMeta.findMappingInputStep();\nif (input == null) throw new IllegalStateException(\"Sub-transformation lacks a Mapping Input step\");\nTransMeta parent = mappingStepMeta.getParentTransMeta();\nif (parent.findMappingInputStep() == null) throw new IllegalStateException(\"Mapping step not wired to sub-transformation\");","typeGuard":"boolean isWired(MappingInputData data) { return data != null && data.sourceSteps != null; }","tryCatchPattern":"try {\n  trans.prepareExecution(new Object[0]);\n  trans.startThreads();\n  trans.waitUntilFinished();\n} catch (KettleException e) {\n  if (e.getMessage().contains(\"Unable to connect with parent transformation\")) {\n    // mapping not wired: check Mapping step config and prepareMappingExecution\n  }\n  throw e;\n}","preventionTips":["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."],"tags":["kettle","pdi","sub-transformation","timeout","mapping-step"],"backgroundTag":"request-timeout","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}