{"record":{"id":"eaf5fe276b2b5270","repo":"pentaho/pentaho-kettle","slug":"tostring-couldn-t-convert-binary-value-to-string-with","errorCode":null,"errorMessage":"<toString()> : couldn't convert binary value to String with specified string encoding [<stringEncoding>]","messagePattern":"<toString\\(\\)> : couldn't convert binary value to String 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":1536,"sourceCode":"    // if (binary==null || binary.length==0) return null;\n    if ( binary == null || binary.length == 0 ) {\n      return ( emptyStringDiffersFromNull && binary != null ) ? \"\" : null;\n    }\n\n    String encoding;\n    if ( identicalFormat ) {\n      encoding = getStringEncoding();\n    } else {\n      encoding = storageMetadata.getStringEncoding();\n    }\n\n    if ( Utils.isEmpty( encoding ) ) {\n      return new String( binary );\n    } else {\n      try {\n        return new String( binary, encoding );\n      } catch ( UnsupportedEncodingException e ) {\n        throw new KettleValueException( toString()\n            + \" : couldn't convert binary value to String with specified string encoding [\" + stringEncoding + \"]\", e );\n      }\n    }\n  }\n\n  /**\n   * Converts the specified data object to the normal storage type.\n   *\n   * @param object\n   *          the data object to convert\n   * @return the data in a normal storage type\n   * @throws KettleValueException\n   *           In case there is a data conversion error.\n   */\n  @Override\n  public Object convertToNormalStorageType( Object object ) throws KettleValueException {\n    if ( object == null ) {\n      return null;","sourceCodeStart":1518,"sourceCodeEnd":1554,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/core/src/main/java/org/pentaho/di/core/row/value/ValueMetaBase.java#L1518-L1554","documentation":"Thrown by ValueMetaBase.convertBinaryStringToString when converting a byte[] to String with an explicitly configured encoding that the JVM does not support (UnsupportedEncodingException). Without an encoding configured, Kettle falls back to the platform default charset and never throws this.","triggerScenarios":"convertBinaryStringToString(byte[]) where setStringEncoding() was given a charset name not present among the JVM's available charsets (typo like 'UTF_8', 'utf8' on very old JVMs, or a vendor-specific name).","commonSituations":"Typo'd encoding in a Text File Input / Fixed File Input step ('ISO-8859-1' misspelled, 'UTF8' vs 'UTF-8' depending on JDK), or an encoding removed/not shipped in a stripped or customized JVM (e.g. compact profiles).","solutions":["Correct the encoding string to a canonical IANA name: 'UTF-8', 'ISO-8859-1', 'US-ASCII', etc.","List available charsets (Charset.availableCharsets()) or run the JVM with -Dfile.encoding and full charsets to confirm what's supported.","Clear the encoding setting to use the JVM default charset if platform default is acceptable.","Upgrade to a full JDK/JRE that includes the needed charset provider if a compact/custom JVM lacks it."],"exampleFix":"// before\nvm.setStringEncoding(\"utf_8\"); // UnsupportedEncodingException\n// after\nvm.setStringEncoding(\"UTF-8\");","handlingStrategy":"validation","validationCode":"try {\n    java.nio.charset.Charset.forName(encoding);\n} catch (java.nio.charset.IllegalCharsetNameException | java.nio.charset.UnsupportedCharsetException e) {\n    throw new IllegalArgumentException(\"Unsupported encoding: \" + encoding);\n}","typeGuard":"static boolean isSupportedCharset(String name) { return name != null && java.nio.charset.Charset.isSupported(name); }","tryCatchPattern":"try {\n    String s = valueMeta.convertBinaryStringToString(bytes);\n} catch (KettleValueException e) {\n    String s = new String(bytes, java.nio.charset.StandardCharsets.UTF_8); // fallback\n}","preventionTips":["Always use canonical charset names: UTF-8, ISO-8859-1, windows-1252","Validate encodings with Charset.isSupported() at configuration time","Pin -Dfile.encoding and test on the target JVM before deployment"],"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"}