{"record":{"id":"c1d5c72b8e057c73","repo":"pentaho/pentaho-kettle","slug":"scriptmeta-exception-fieldtoreplacenotfound","errorCode":null,"errorMessage":"ScriptMeta.Exception.FieldToReplaceNotFound","messagePattern":"ScriptMeta\\.Exception\\.FieldToReplaceNotFound","errorType":"exception","errorClass":"KettleStepException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/script/ScriptMeta.java","lineNumber":288,"sourceCode":"      precision[i] = -1;\n      replace[i] = false;\n    }\n  }\n\n  @Override\n  public void getFields( Bowl bowl, RowMetaInterface row, String originStepname, RowMetaInterface[] info, StepMeta nextStep,\n    VariableSpace space, Repository repository, IMetaStore metaStore ) throws KettleStepException {\n    for ( int i = 0; i < fieldname.length; i++ ) {\n      if ( !Utils.isEmpty( fieldname[i] ) ) {\n        String fieldName;\n        int replaceIndex;\n        int fieldType;\n\n        if ( replace[i] ) {\n          // Look up the field to replace...\n          //\n          if ( row.searchValueMeta( fieldname[i] ) == null && Utils.isEmpty( rename[i] ) ) {\n            throw new KettleStepException( BaseMessages.getString(\n              PKG, \"ScriptMeta.Exception.FieldToReplaceNotFound\", fieldname[i] ) );\n          }\n          replaceIndex = row.indexOfValue( rename[i] );\n\n          // Change the data type to match what's specified...\n          //\n          fieldType = type[i];\n          fieldName = rename[i];\n        } else {\n          replaceIndex = -1;\n          fieldType = type[i];\n          if ( rename[i] != null && rename[i].length() != 0 ) {\n            fieldName = rename[i];\n          } else {\n            fieldName = fieldname[i];\n          }\n        }\n        try {","sourceCodeStart":270,"sourceCodeEnd":306,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/script/ScriptMeta.java#L270-L306","documentation":"In getFields(), when a Script step output field is marked replace=true but the incoming row has no field with that name AND no rename target is set, the step cannot determine which field to replace. It throws KettleStepException 'FieldToReplaceNotFound' naming the field.","triggerScenarios":"Field name in the Script step's output definition (fieldname[i]) does not match any incoming row field while replace[i] is true and rename[i] is empty.","commonSituations":"Upstream step renamed or dropped the field the script was supposed to overwrite; user typed the wrong field name; change introduced by editing an earlier step in the transformation.","solutions":["Correct the field name in the Script step's Fields tab so it matches the actual incoming row field.","If the goal is to create a new field, uncheck 'Replace value' for that field.","Fill in the Rename field to redirect the replacement to the correct target.","Inspect the upstream step's output (View data) to confirm the exact field name."],"exampleFix":"// before (Script step Fields tab config)\nfieldname='cust_id', replace=true, rename=''\n// after (match upstream field name)\nfieldname='customer_id', replace=true, rename=''","handlingStrategy":"validation","validationCode":"// In Spoon: preview the upstream step output and confirm field names\n// or in code, before executing:\nif (replace[i] && row.searchValueMeta(fieldname[i]) == null && Utils.isEmpty(rename[i])) {\n  throw new IllegalArgumentException(\"Field to replace not found: \" + fieldname[i]);\n}","typeGuard":null,"tryCatchPattern":"try { step.getFields(row, ...); } catch (KettleStepException e) {\n  if (e.getMessage().contains(\"FieldToReplaceNotFound\")) {\n    // uncheck 'replace' or fix the field name in the step dialog\n  }\n}","preventionTips":["Preview upstream rows before wiring replace fields","Keep field names in a shared constants/convention","Re-check Script step Fields tab after changing upstream steps","Prefer creating new fields over replace when unsure"],"tags":["pdi","row-metadata","field-mapping","kettle"],"backgroundTag":"record-not-found","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"}