pentaho/pentaho-kettle · error · KettleException

Unexpected error while encoding binary fields

Error message

Unexpected error while encoding binary fields

What it means

In the TextFileOutput constructor the step precomputes binary separators, enclosures, newlines and null values using the configured encoding. Any unexpected exception during this binary-field setup is wrapped in KettleException 'Unexpected error while encoding binary fields'.

Solutions

1. Reopen the step dialog and re-set separator, enclosure and encoding values
2. Verify the configured encoding is supported by the JVM
3. Reload/re-save the transformation to repair corrupted metadata

Example fix

// before
meta.setEncoding( "x-custom-charset" );
// after
meta.setEncoding( "UTF-8" );

if ( meta.getEncoding() != null && !java.nio.charset.Charset.isSupported( meta.getEncoding() ) ) throw new IllegalArgumentException( "Unsupported encoding in step metadata" );

try { init(); } catch ( KettleException e ) { logError( "Step init failed while encoding binary fields: " + e.getCause() ); throw e; }

When it happens

Trigger: Encoding a separator/enclosure/null string fails in init (e.g. unsupported charset, invalid regex-based escape handling, NPE on meta fields) during step initialization.

Common situations: Invalid step metadata (missing separator or encoding), charset unsupported, corrupted transformation metadata after upgrade.

Related errors

• Following required files are missing:
• LoadFileInput.Log.RequiredFilesMissing
• Unable to convert String to Binary with specified string…
• A deadlock was detected between steps
• AbsSecurityManager.ERROR_0003_UNABLE_TO_ACCESS_ROLE_BINDING_WEBSVC

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

Appendix: source

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

          data.binaryNewline = environmentSubstitute( meta.getNewline() ).getBytes();
        }
      }

      data.binaryNullValue = new byte[meta.getOutputFields().length][];
      for ( int i = 0; i < meta.getOutputFields().length; i++ ) {
        data.binaryNullValue[i] = null;
        String nullString = meta.getOutputFields()[i].getNullString();
        if ( !Utils.isEmpty( nullString ) ) {
          if ( data.hasEncoding ) {
            data.binaryNullValue[i] = nullString.getBytes( meta.getEncoding() );
          } else {
            data.binaryNullValue[i] = nullString.getBytes();
          }
        }
      }
      data.splitEvery = meta.getSplitEvery( variables );
    } catch ( Exception e ) {
      throw new KettleException( "Unexpected error while encoding binary fields", e );
    }
  }

  protected void close() throws IOException {
    if ( !meta.isServletOutput() ) {
      data.getFileStreamsCollection().flushOpenFiles( true );
    }
  }

  public void dispose( StepMetaInterface smi, StepDataInterface sdi ) {
    meta = (TextFileOutputMeta) smi;
    data = (TextFileOutputData) sdi;

    try {
      close();
    } catch ( Exception e ) {
      logError( "Unexpected error closing file", e );
      setErrors( 1 );

View on GitHub (pinned to f3058517a1)