{"record":{"id":"b53250a5ea9ccc89","repo":"pentaho/pentaho-kettle","slug":"tostring-couldn-t-convert-string-to-binary-with-specified","errorCode":null,"errorMessage":"<toString()> : couldn't convert String to Binary with specified string encoding [<stringEncoding>]","messagePattern":"<toString\\(\\)> : couldn't convert String to Binary with specified string encoding \\[<stringEncoding>\\]","errorType":"exception","errorClass":"KettleValueException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/pentaho/di/core/row/value/ValueMetaBase.java","lineNumber":1651,"sourceCode":"    }\n\n    String string = getString( object );\n\n    return convertStringToBinaryString( string );\n  }\n\n  protected byte[] convertStringToBinaryString( String string ) throws KettleValueException {\n    if ( string == null ) {\n      return null;\n    }\n\n    if ( Utils.isEmpty( stringEncoding ) ) {\n      return string.getBytes();\n    } else {\n      try {\n        return string.getBytes( stringEncoding );\n      } catch ( UnsupportedEncodingException e ) {\n        throw new KettleValueException( toString()\n            + \" : couldn't convert String to Binary with specified string encoding [\" + stringEncoding + \"]\", e );\n      }\n    }\n  }\n\n  /**\n   * Clones the data. Normally, we don't have to do anything here, but just for arguments and safety, we do a little\n   * extra work in case of binary blobs and Date objects. We should write a programmers manual later on to specify in\n   * all clarity that \"we always overwrite/replace values in the Object[] data rows, we never modify them\" .\n   *\n   * @return a cloned data object if needed\n   */\n  @Override\n  public Object cloneValueData( Object object ) throws KettleValueException {\n    if ( object == null ) {\n      return null;\n    }\n","sourceCodeStart":1633,"sourceCodeEnd":1669,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/core/src/main/java/org/pentaho/di/core/row/value/ValueMetaBase.java#L1633-L1669","documentation":"Thrown by ValueMetaBase.convertStringToBinary when converting a String to byte[] with a configured encoding the JVM doesn't recognize (UnsupportedEncodingException). Empty stringEncoding falls back to String.getBytes() with the platform default and cannot throw this.","triggerScenarios":"convertStringToBinary(String) (used when writing text files, building binary-string storage) with setStringEncoding() given an unsupported name such as 'UTF_8', 'WIN1252', or a charset absent from the JRE.","commonSituations":"Text File Output steps with a mistyped 'Encoding' dropdown value typed manually; running on a stripped/compact JVM lacking extended charsets; copying encoding names from other systems (e.g. database code pages like 'CP1252' vs 'windows-1252').","solutions":["Use a canonical charset name ('UTF-8', 'windows-1252', 'ISO-8859-1') — verify with Charset.forName(name) beforehand.","Clear the encoding to use the JVM/platform default if charset fidelity isn't required.","Run with a full JDK that includes all standard charsets (java.nio.charset.spi providers).","Catch UnsupportedEncodingException at the step level and fall back to UTF-8 with a log warning."],"exampleFix":"// before\nbyte[] b = valueMeta.convertStringToBinary(s); // encoding \"UTF_8\" set\n// after\nvm.setStringEncoding(Charset.forName(\"UTF-8\").name()); // validates name; \"UTF-8\"","handlingStrategy":"validation","validationCode":"if (encoding != null && !encoding.isEmpty() && !java.nio.charset.Charset.isSupported(encoding)) {\n    throw new IllegalArgumentException(\"Charset not supported by this JVM: \" + encoding);\n}","typeGuard":"static boolean isValidEncoding(String enc) {\n    return enc == null || enc.isEmpty() || java.nio.charset.Charset.isSupported(enc);\n}","tryCatchPattern":"try {\n    byte[] b = valueMeta.convertStringToBinary(s);\n} catch (KettleValueException e) {\n    byte[] b = s.getBytes(java.nio.charset.StandardCharsets.UTF_8); // safe fallback\n}","preventionTips":["Pick encodings from the step's dropdown rather than typing free-text names","Canonicalize with Charset.forName(...).name() when setting encodings programmatically","Smoke-test file output on the deployment JVM, especially on compact/stripped JREs"],"tags":["pdi","encoding","charset","kettle"],"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"}