{"record":{"id":"ca5a2175a51a8a32","repo":"pentaho/pentaho-kettle","slug":"unsupported-situation-detected-where-a-remote-output-step-is","errorCode":null,"errorMessage":"Unsupported situation detected where a remote output step is expecting data to end up in a particular Mapping Output step of a sub-transformation.  To solve it, insert a dummy step after the mapping.","messagePattern":"Unsupported situation detected where a remote output step is expecting data to end up in a particular Mapping Output step of a sub-transformation\\.  To solve it, insert a dummy step after the mapping\\.","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/mapping/Mapping.java","lineNumber":183,"sourceCode":"            // over remotely to this mapping.\n            // However, the data needs to end up at a Mapping Output step of the\n            // sub-transformation, not in this step.\n            // We can move over the remote steps to the Mapping Output step as long\n            // as the threads haven't started yet.\n            //\n            for ( RemoteStep remoteStep : getRemoteOutputSteps() ) {\n              // Pass this rowset down to a mapping output step in the\n              // sub-transformation...\n              //\n              if ( mappingOutputs.length == 1 ) {\n                // Simple case: only one output mapping. Move the remote step over\n                //\n                mappingOutputs[0].getRemoteOutputSteps().add( remoteStep );\n              } else {\n                // TODO: figure out where this remote step needs to go and where\n                // it comes from.\n                //\n                throw new KettleException(\n                    \"Unsupported situation detected where a remote output step is expecting data \"\n                        + \"to end up in a particular Mapping Output step of a sub-transformation.  \"\n                        + \"To solve it, insert a dummy step after the mapping.\" );\n              }\n            }\n            getRemoteOutputSteps().clear();\n          }\n\n          // Start the mapping/sub-transformation threads\n          //\n          getData().getMappingTrans().startThreads();\n\n          // The transformation still runs in the background and might have some\n          // more work to do.\n          // Since everything is running in the MappingThreads we don't have to do\n          // anything else here but wait...\n          //\n          if ( getTransMeta().getTransformationType() == TransformationType.Normal ) {","sourceCodeStart":165,"sourceCodeEnd":201,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/mapping/Mapping.java#L165-L201","documentation":"In Mapping.processRow, remote output steps are added to mappingOutputs[0].getRemoteOutputSteps(). When the sub-transformation has multiple Mapping Output steps, the remote output step cannot be assigned unambiguously, so this KettleException is thrown. It enforces a single destination for remotely consumed output in clustered execution.","triggerScenarios":"Clustered/remote execution where the Mapping step's sub-transformation contains multiple Mapping Output steps, and a remote output step expects data from one specific Mapping Output — during remote-output wiring in processRow.","commonSituations":"Deploying a locally developed transformation (sub-transf with several Mapping Outputs) onto a cluster; cluster schema changes making previously local hops remote.","solutions":["Insert a Dummy step after the Mapping step to disambiguate output wiring.","Reduce the sub-transformation to a single Mapping Output step.","Adjust cluster schema / step copy settings so the output hop is not remote to multiple Mapping Outputs.","Redesign with explicit 'Mapping (sub-transformation)' output specification if multiple outputs are required."],"exampleFix":"// before (clustered)\nMapping(sub.ktr) =====> RemoteOutput  // sub.ktr: 2x MappingOutput\n// after\nMapping(sub.ktr) =====> Dummy =====> RemoteOutput  // or single MappingOutput","handlingStrategy":"validation","validationCode":"// Before clustered execution, assert single Mapping Output in the sub-transformation:\nlong mappingOutputs = subTransMeta.getSteps().stream()\n  .filter(s -> s.getStepMeta() instanceof MappingOutputMeta).count();\nif (mappingOutputs > 1) throw new IllegalStateException(\"Remote execution requires exactly one Mapping Output\");","typeGuard":null,"tryCatchPattern":"try {\n  trans.execute(new String[0]); // clustered run\n} catch (KettleException e) {\n  if (e.getMessage().contains(\"remote output step\")) {\n    log.error(\"Remote output cannot target multiple Mapping Outputs: add Dummy step or reduce to one\", e);\n  } else { throw e; }\n}","preventionTips":["Audit sub-transformations for multiple Mapping Outputs before clustering.","Check cluster schema settings so output hops are not ambiguously remote.","Test single-threaded/local runs before deploying to the cluster.","Add Dummy steps to disambiguate mapping-to-downstream hops."],"tags":["mapping","cluster","sub-transformation","kettle"],"backgroundTag":"invalid-state-transition","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"}