pentaho/pentaho-kettle · error · KettleValueException

<toString()> : couldn't convert binary value to String with…

Error message

<toString()> : couldn't convert binary value to String with specified string encoding [<stringEncoding>]

What it means

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.

Solutions

  1. Correct the encoding string to a canonical IANA name: 'UTF-8', 'ISO-8859-1', 'US-ASCII', etc.
  2. List available charsets (Charset.availableCharsets()) or run the JVM with -Dfile.encoding and full charsets to confirm what's supported.
  3. Clear the encoding setting to use the JVM default charset if platform default is acceptable.
  4. Upgrade to a full JDK/JRE that includes the needed charset provider if a compact/custom JVM lacks it.

Example fix

// before
vm.setStringEncoding("utf_8"); // UnsupportedEncodingException
// after
vm.setStringEncoding("UTF-8");
Defensive patterns

Strategy: validation

Validate before calling

try {
    java.nio.charset.Charset.forName(encoding);
} catch (java.nio.charset.IllegalCharsetNameException | java.nio.charset.UnsupportedCharsetException e) {
    throw new IllegalArgumentException("Unsupported encoding: " + encoding);
}

Type guard

static boolean isSupportedCharset(String name) { return name != null && java.nio.charset.Charset.isSupported(name); }

Try / catch

try {
    String s = valueMeta.convertBinaryStringToString(bytes);
} catch (KettleValueException e) {
    String s = new String(bytes, java.nio.charset.StandardCharsets.UTF_8); // fallback
}

Prevention

When it happens

Trigger: 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).

Common situations: 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).

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of pentaho/pentaho-kettle@f3058517a1 (2026-09-13). Data as JSON: /api/errors/eaf5fe276b2b5270. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/core/row/value/ValueMetaBase.java:1536

    // if (binary==null || binary.length==0) return null;
    if ( binary == null || binary.length == 0 ) {
      return ( emptyStringDiffersFromNull && binary != null ) ? "" : null;
    }

    String encoding;
    if ( identicalFormat ) {
      encoding = getStringEncoding();
    } else {
      encoding = storageMetadata.getStringEncoding();
    }

    if ( Utils.isEmpty( encoding ) ) {
      return new String( binary );
    } else {
      try {
        return new String( binary, encoding );
      } catch ( UnsupportedEncodingException e ) {
        throw new KettleValueException( toString()
            + " : couldn't convert binary value to String with specified string encoding [" + stringEncoding + "]", e );
      }
    }
  }

  /**
   * Converts the specified data object to the normal storage type.
   *
   * @param object
   *          the data object to convert
   * @return the data in a normal storage type
   * @throws KettleValueException
   *           In case there is a data conversion error.
   */
  @Override
  public Object convertToNormalStorageType( Object object ) throws KettleValueException {
    if ( object == null ) {
      return null;

View on GitHub (pinned to f3058517a1)