{"record":{"id":"03784cdba7cb09b1","repo":"pentaho/pentaho-kettle","slug":"replace-by-value-field-is-missing-at-position-0","errorCode":null,"errorMessage":"Replace by value field is missing at position {0}","messagePattern":"Replace by value field is missing at position (.+?)","errorType":"exception","errorClass":"KettleStepException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/setvaluefield/SetValueField.java","lineNumber":90,"sourceCode":"          if ( meta.getFieldName()[j].equals( meta.getFieldName()[i] ) ) {\n            if ( j != i ) {\n              throw new KettleException( BaseMessages.getString(\n                PKG, \"SetValueField.Log.FieldSpecifiedMoreThatOne\", meta.getFieldName()[i], \"\" + i, \"\" + j ) );\n            }\n          }\n        }\n\n        data.indexOfField[i] = data.outputRowMeta.indexOfValue( environmentSubstitute( meta.getFieldName()[i] ) );\n        if ( data.indexOfField[i] < 0 ) {\n          throw new KettleStepException( BaseMessages.getString(\n            PKG, \"SetValueField.Log.CouldNotFindFieldInRow\", meta.getFieldName()[i] ) );\n        }\n        String sourceField = environmentSubstitute(\n          meta.getReplaceByFieldValue() != null && meta.getReplaceByFieldValue().length > 0\n            ? meta.getReplaceByFieldValue()[i] : null\n        );\n        if ( Utils.isEmpty( sourceField ) ) {\n          throw new KettleStepException( BaseMessages.getString(\n            PKG, \"SetValueField.Log.ReplaceByValueFieldMissing\", \"\" + i ) );\n        }\n        data.indexOfReplaceByValue[i] = data.outputRowMeta.indexOfValue( sourceField );\n        if ( data.indexOfReplaceByValue[i] < 0 ) {\n          throw new KettleStepException( BaseMessages.getString(\n            PKG, \"SetValueField.Log.CouldNotFindFieldInRow\", sourceField ) );\n        }\n        // Compare fields type\n        ValueMetaInterface SourceValue = getInputRowMeta().getValueMeta( data.indexOfField[i] );\n        ValueMetaInterface ReplaceByValue = getInputRowMeta().getValueMeta( data.indexOfReplaceByValue[i] );\n\n        if ( SourceValue.getType() != ReplaceByValue.getType() ) {\n          String err =\n            BaseMessages.getString( PKG, \"SetValueField.Log.FieldsTypeDifferent\", SourceValue.getName()\n              + \" (\" + SourceValue.getTypeDesc() + \")\", ReplaceByValue.getName()\n              + \" (\" + ReplaceByValue.getTypeDesc() + \")\" );\n          throw new KettleStepException( err );\n        }","sourceCodeStart":72,"sourceCodeEnd":108,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/setvaluefield/SetValueField.java#L72-L108","documentation":"The Set Value Field step requires both a target field and a 'replace by value' field for each mapping. When the configured replace-by source field is empty or missing at position i, processRow throws this KettleStepException, because the step has no source whose value can be copied into the target field.","triggerScenarios":"processRow reads meta.getReplaceByFieldValue()[i], applies environmentSubstitute, and calls Utils.isEmpty(sourceField); if the replace-by field setting is null, an empty array element, or a variable that resolves to empty string, the exception fires with the mapping index i.","commonSituations":"A mapping row was added in the step dialog but the 'Replace by value' column was left blank; the value is a variable like ${SRC_FIELD} that is not defined in the run environment; a mapping was partially deleted leaving a dangling entry; importing a transformation from XML where the replaceby tag was empty.","solutions":["Open the Set Value Field step and fill in the 'Replace by value' field for every mapping row; the message's position number tells you which row (0-based).","If the value uses a variable, confirm the variable is set in kettle.properties / run configuration / Set Variables step.","Remove any unused/blank mapping rows from the step's field table.","Validate the transformation with the 'Verify transformations' tool or preview the step before running the full transformation."],"exampleFix":"// before (in step metadata XML)\n<replaceby></replaceby>\n// after\n<replaceby>order_total</replaceby>","handlingStrategy":"validation","validationCode":"// Validate step metadata before execution\nfor (int i = 0; i < meta.getReplaceByFieldValue().length; i++) {\n  if (Utils.isEmpty(environmentSubstitute(meta.getReplaceByFieldValue()[i]))) {\n    throw new IllegalStateException(\"Replace-by field empty at position \" + i);\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  trans.execute(null);\n} catch (KettleStepException e) {\n  log.error(\"Missing replace-by field: {}\", e.getMessage());\n}","preventionTips":["Fill both columns of the Set Value Field table; never leave 'Replace by value' blank","Delete unused mapping rows before saving","Keep defining variables in kettle.properties or the run configuration documented","Use the transformation validator before scheduling"],"tags":["kettle","configuration","missing-field","set-value-field"],"backgroundTag":"missing-required-config-field","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"}