pentaho/pentaho-kettle · error · KettleException

Error converting string to binary

Error message

Error converting string to binary

What it means

The string-to-binary helper (used for encoding/optionally gzip-compressing a string into bytes) wraps any exception during the conversion into KettleException("Error converting string to binary"). Causes (unsupported charset name, gzip stream failure) are chained in the cause.

Solutions

1. Check e.getCause() for UnsupportedEncodingException and correct the charset name (use StandardCharsets.UTF_8.name()).
2. Use a charset constant instead of a free-form string to avoid typos.
3. Increase heap (-Xmx) if compressing very large strings.
4. Avoid gzip if the caller only needs raw bytes and compression is optional.

Example fix

// before
byte[] bytes = XMLHandler.stringToBinary(str, "utf-8", true); // typo charset
// after
byte[] bytes = XMLHandler.stringToBinary(str, StandardCharsets.UTF_8.name(), true);

try { "x".getBytes(charsetName); } catch (UnsupportedEncodingException e) { /* fix charset */ }

boolean isSupportedCharset(String name) {
  try { java.nio.charset.Charset.forName(name); return true; }
  catch (Exception e) { return false; }
}

try {
  bytes = XMLHandler.stringToBinary(str, charset, compress);
} catch (KettleException e) {
  throw new KettleException("Encode failed with charset " + charset + ": " + e.getCause(), e);
}

When it happens

Trigger: Calling the XMLHandler stringToBinary-style method with a charset name unsupported by the JVM, or when the GZIPOutputStream fails mid-write (out of memory, stream closed prematurely).

Common situations: Hardcoded charset names with typos (e.g. "UTF8" vs typo), running on a JVM with a restricted charset provider, very large strings exhausting memory during gzip.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Can't encode object of class : className
• ChangeFileEncoding.Exception.TargetEncodingEmpty
• ConcatFields.Error.UnsupportedEncoding
• CsvInput.Log.Error.ErrorConvertingLine (with e.toString())
• e.getMessage()

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

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/core/xml/XMLHandler.java:1231

          byte[] tmp = new byte[ newSize ];
          for ( int i = 0; i < result.length; i++ ) {
            tmp[ i ] = result[ i ];
          }
          for ( int i = 0; i < nrExtra; i++ ) {
            tmp[ result.length + i ] = extra[ i ];
          }

          // change the result
          result = tmp;
          nrExtra = bi.read( extra );
        }
        bytes = result;
        gzip.close();
      }

      return bytes;
    } catch ( Exception e ) {
      throw new KettleException( "Error converting string to binary", e );
    }
  }

  public static String buildCDATA( String string ) {
    return buildCDATA( new StringBuilder(), string ).toString();
  }

  public static StringBuilder buildCDATA( StringBuilder builder, String string ) {
    return builder.append( "<![CDATA[" ).append( Const.NVL( string, "" ) ).append( "]]>" );
  }

  public static String openTag( String tag ) {
    return openTag( new StringBuilder(), tag ).toString();
  }

  public static StringBuilder openTag( StringBuilder builder, String tag ) {
    return builder.append( '<' ).append( tag ).append( '>' );
  }

View on GitHub (pinned to f3058517a1)