{"record":{"id":"5424ae480264bc88","repo":"pentaho/pentaho-kettle","slug":"unable-to-convert-string-to-binary-with-specified-string","errorCode":null,"errorMessage":"Unable to convert String to Binary with specified string encoding [{0}]","messagePattern":"Unable to convert String to Binary with specified string encoding \\[(.+?)\\]","errorType":"exception","errorClass":"KettleValueException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/textfileoutput/TextFileOutput.java","lineNumber":539,"sourceCode":"  }\n\n  private byte[] convertStringToBinaryString( ValueMetaInterface v, String string ) throws KettleValueException {\n    int length = v.getLength();\n\n    if ( string == null ) {\n      return new byte[] {};\n    }\n\n    if ( length > -1 && length < string.length() ) {\n      // we need to truncate\n      String tmp = string.substring( 0, length );\n      if ( Utils.isEmpty( v.getStringEncoding() ) ) {\n        return tmp.getBytes();\n      } else {\n        try {\n          return tmp.getBytes( v.getStringEncoding() );\n        } catch ( UnsupportedEncodingException e ) {\n          throw new KettleValueException( \"Unable to convert String to Binary with specified string encoding [\"\n              + v.getStringEncoding() + \"]\", e );\n        }\n      }\n    } else {\n      byte[] text;\n      if ( Utils.isEmpty( meta.getEncoding() ) ) {\n        text = string.getBytes();\n      } else {\n        try {\n          text = string.getBytes( meta.getEncoding() );\n        } catch ( UnsupportedEncodingException e ) {\n          throw new KettleValueException( \"Unable to convert String to Binary with specified string encoding [\"\n              + v.getStringEncoding() + \"]\", e );\n        }\n      }\n      if ( length > string.length() ) {\n        // we need to pad this\n","sourceCodeStart":521,"sourceCodeEnd":557,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/textfileoutput/TextFileOutput.java#L521-L557","documentation":"In binary (fast) mode a String field value is converted to bytes using the field's own string encoding. When that charset name is not a supported encoding, UnsupportedEncodingException is wrapped in KettleValueException 'Unable to convert String to Binary with specified string encoding [...]'.","triggerScenarios":"Field-level 'String encoding' (v.getStringEncoding()) set to an invalid/unsupported charset name in formatField -> convertStringToBinaryString.","commonSituations":"Typo like 'utf-8 ' with spaces or 'utf8' vs 'UTF-8' on a JVM lacking that alias; wrong case-sensitive name; encoding configured on the wrong field.","solutions":["Set the field's string encoding to a valid charset name supported by the JVM (e.g. 'UTF-8', 'ISO-8859-1')","Clear the field-level encoding so it falls back to the step's encoding","Verify available charsets with Charset.availableCharsets()"],"exampleFix":"// before\nv.setStringEncoding( \"utf-8 \" ); // trailing space -> UnsupportedEncodingException\n// after\nv.setStringEncoding( \"UTF-8\" );","handlingStrategy":"validation","validationCode":"try { java.nio.charset.Charset.forName( fieldEncoding ); } catch ( Exception e ) { throw new IllegalArgumentException( \"Unsupported field encoding: \" + fieldEncoding ); }","typeGuard":"boolean isSupportedCharset( String name ) { return name != null && java.nio.charset.Charset.isSupported( name.trim() ); }","tryCatchPattern":"try { writeRowTo( row ); } catch ( KettleValueException e ) { if ( e.getMessage().contains( \"string encoding\" ) ) logError( \"Fix encoding for field: \" + e.getMessage() ); }","preventionTips":["Only select encodings from the step's dropdown list","Use UTF-8 unless a legacy requirement exists","Trim user-typed encoding names"],"tags":["kettle","pentaho","encoding","charset"],"backgroundTag":"invalid-config-value","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"}