pentaho/pentaho-kettle · error · KettleValueException

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

Error message

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

What it means

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.

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.

Example fix

// before
byte[] b = valueMeta.convertStringToBinary(s); // encoding "UTF_8" set
// after
vm.setStringEncoding(Charset.forName("UTF-8").name()); // validates name; "UTF-8"

Defensive patterns

Strategy: validation

Validate before calling

if (encoding != null && !encoding.isEmpty() && !java.nio.charset.Charset.isSupported(encoding)) {
    throw new IllegalArgumentException("Charset not supported by this JVM: " + encoding);
}

Type guard

static boolean isValidEncoding(String enc) {
    return enc == null || enc.isEmpty() || java.nio.charset.Charset.isSupported(enc);
}

Try / catch

try {
    byte[] b = valueMeta.convertStringToBinary(s);
} catch (KettleValueException e) {
    byte[] b = s.getBytes(java.nio.charset.StandardCharsets.UTF_8); // safe fallback
}

Prevention

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

When it happens

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

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

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/b53250a5ea9ccc89. Report an issue: GitHub.

Appendix: source

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

    }

    String string = getString( object );

    return convertStringToBinaryString( string );
  }

  protected byte[] convertStringToBinaryString( String string ) throws KettleValueException {
    if ( string == null ) {
      return null;
    }

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

  /**
   * Clones the data. Normally, we don't have to do anything here, but just for arguments and safety, we do a little
   * extra work in case of binary blobs and Date objects. We should write a programmers manual later on to specify in
   * all clarity that "we always overwrite/replace values in the Object[] data rows, we never modify them" .
   *
   * @return a cloned data object if needed
   */
  @Override
  public Object cloneValueData( Object object ) throws KettleValueException {
    if ( object == null ) {
      return null;
    }

View on GitHub (pinned to f3058517a1)