pentaho/pentaho-kettle · error · KettleValueException

Unable to convert String to Binary with specified string…

Error message

Unable to convert String to Binary with specified string encoding [{0}]

What it means

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 [...]'.

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()

Example fix

// before
v.setStringEncoding( "utf-8 " ); // trailing space -> UnsupportedEncodingException
// after
v.setStringEncoding( "UTF-8" );

Defensive patterns

Strategy: validation

Validate before calling

try { java.nio.charset.Charset.forName( fieldEncoding ); } catch ( Exception e ) { throw new IllegalArgumentException( "Unsupported field encoding: " + fieldEncoding ); }

Type guard

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

Try / catch

try { writeRowTo( row ); } catch ( KettleValueException e ) { if ( e.getMessage().contains( "string encoding" ) ) logError( "Fix encoding for field: " + e.getMessage() ); }

Prevention

Only select encodings from the step's dropdown list
Use UTF-8 unless a legacy requirement exists
Trim user-typed encoding names

When it happens

Trigger: Field-level 'String encoding' (v.getStringEncoding()) set to an invalid/unsupported charset name in formatField -> convertStringToBinaryString.

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

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/textfileoutput/TextFileOutput.java:539

  }

  private byte[] convertStringToBinaryString( ValueMetaInterface v, String string ) throws KettleValueException {
    int length = v.getLength();

    if ( string == null ) {
      return new byte[] {};
    }

    if ( length > -1 && length < string.length() ) {
      // we need to truncate
      String tmp = string.substring( 0, length );
      if ( Utils.isEmpty( v.getStringEncoding() ) ) {
        return tmp.getBytes();
      } else {
        try {
          return tmp.getBytes( v.getStringEncoding() );
        } catch ( UnsupportedEncodingException e ) {
          throw new KettleValueException( "Unable to convert String to Binary with specified string encoding ["
              + v.getStringEncoding() + "]", e );
        }
      }
    } else {
      byte[] text;
      if ( Utils.isEmpty( meta.getEncoding() ) ) {
        text = string.getBytes();
      } else {
        try {
          text = string.getBytes( meta.getEncoding() );
        } catch ( UnsupportedEncodingException e ) {
          throw new KettleValueException( "Unable to convert String to Binary with specified string encoding ["
              + v.getStringEncoding() + "]", e );
        }
      }
      if ( length > string.length() ) {
        // we need to pad this

View on GitHub (pinned to f3058517a1)