{"record":{"id":"cca4df667e5b17c7","repo":"pentaho/pentaho-kettle","slug":"changefileencoding-exception-targetencodingempty","errorCode":"ChangeFileEncoding.Exception.TargetEncodingEmpty","errorMessage":"ChangeFileEncoding.Exception.TargetEncodingEmpty","messagePattern":"ChangeFileEncoding\\.Exception\\.TargetEncodingEmpty","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"plugins/core/impl/src/main/java/org/pentaho/di/trans/steps/changefileencoding/ChangeFileEncoding.java","lineNumber":114,"sourceCode":"      if ( data.indexOfTargetFileename < 0 ) {\n        // The field is unreachable !\n        logError( BaseMessages.getString( PKG, \"ChangeFileEncoding.Exception.CouldnotFindField\" ) + \"[\"\n            + meta.getTargetFilenameField() + \"]\" );\n        throw new KettleException( BaseMessages.getString( PKG, \"ChangeFileEncoding.Exception.CouldnotFindField\",\n          meta.getTargetFilenameField() ) );\n      }\n\n      // Check source encoding\n      data.sourceEncoding = environmentSubstitute( meta.getSourceEncoding() );\n\n      // if(Utils.isEmpty(data.sourceEncoding)) {\n      // throw new KettleException(BaseMessages.getString(PKG, \"ChangeFileEncoding.Exception.SourceEncodingEmpty\"));\n      // }\n      // Check target encoding\n      data.targetEncoding = environmentSubstitute( meta.getTargetEncoding() );\n\n      if ( Utils.isEmpty( data.targetEncoding ) ) {\n        throw new KettleException( BaseMessages.getString( PKG, \"ChangeFileEncoding.Exception.TargetEncodingEmpty\" ) );\n      }\n\n      // End If first\n    }\n\n    try {\n      // get source filename\n      String sourceFilename = data.inputRowMeta.getString( outputRow, data.indexOfFileename );\n      if ( Utils.isEmpty( sourceFilename ) ) {\n        throw new KettleException( BaseMessages.getString( PKG, \"ChangeFileEncoding.Error.SourceFileIsEmpty\",\n          meta.getDynamicFilenameField() ) );\n      }\n\n      // get target filename\n      String targetFilename = data.inputRowMeta.getString( outputRow, data.indexOfTargetFileename );\n      if ( Utils.isEmpty( targetFilename ) ) {\n        throw new KettleException( BaseMessages.getString( PKG, \"ChangeFileEncoding.Error.TargetFileIsEmpty\",\n          meta.getTargetFilenameField() ) );","sourceCodeStart":96,"sourceCodeEnd":132,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/plugins/core/impl/src/main/java/org/pentaho/di/trans/steps/changefileencoding/ChangeFileEncoding.java#L96-L132","documentation":"After substituting variables in the target encoding setting, the step validates it is non-empty and throws this localized KettleException when no target character encoding (e.g. UTF-8, ISO-8859-1) has been configured. Without it the step cannot know how to write the converted file.","triggerScenarios":"processRow on the first row when Utils.isEmpty(data.targetEncoding) is true — 'Target encoding' empty in the dialog or the variable used for it (e.g. ${TARGET_ENC}) resolves to empty/null.","commonSituations":"Encoding field left blank; environment variable or parameter not defined in the runtime environment (kitchen/pan without the parameter set); variable misspelled so it substitutes to empty.","solutions":["Set 'Target encoding' in the step dialog to a valid charset name (e.g. UTF-8).","If a variable is used, define it in the transformation settings, kettle.properties, or pass it via -param on pan/kitchen.","Verify the resolved value with 'Show variables' or logging before the step.","Note the source-encoding check is commented out in the code, so only the target encoding is validated here."],"exampleFix":"// before\ntargetEncoding = ${UNDEFINED_VAR}; // resolves to empty\n// after\ntargetEncoding = UTF-8; // or define ${TARGET_ENC}=UTF-8","handlingStrategy":"validation","validationCode":"String enc = transMeta.environmentSubstitute(meta.getTargetEncoding());\nif (enc == null || enc.isEmpty()) {\n  throw new IllegalArgumentException(\"Target encoding must be set (e.g. UTF-8)\");\n}\nCharset.forName(enc); // also validate it is a supported charset","typeGuard":null,"tryCatchPattern":"try {\n  // execute transformation\n} catch (KettleException e) {\n  if (e.getMessage().contains(\"TargetEncodingEmpty\")) {\n    // set target encoding / define the variable\n  } else { throw e; }\n}","preventionTips":["Always set a concrete charset like UTF-8","When using variables, define them in kettle.properties or pass via -param","Validate the charset name with Charset.forName at config time"],"tags":["kettle","configuration","encoding","variables"],"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"}