pentaho/pentaho-kettle · error · KettleException

ChangeFileEncoding.Error.CreatingFile

ChangeFileEncoding.Error.CreatingFile

Error message

ChangeFileEncoding.Error.CreatingFile

What it means

Generic wrapper: any exception thrown while changeEncoding() reads the source stream and writes the re-encoded target file (open, read, write, or charset conversion failures) is caught and rethrown as a KettleException with the CreatingFile message, chaining the original cause. The real reason is always in the nested exception.

Solutions

  1. Inspect the chained cause exception in the log to find the underlying IO/charset error.
  2. Validate encoding names against java.nio.charset.Charset.isSupported(name) (use 'UTF-8', 'ISO-8859-1', etc.).
  3. Check write permissions on the target directory and free disk space.
  4. Close other processes holding the target file open.

Example fix

// before
String encoding = "utf8";
// after
String encoding = Charset.isSupported( "utf8" ) ? "utf8" : "UTF-8"; // use canonical 'UTF-8'
Defensive patterns

Strategy: try-catch

Validate before calling

// validate encodings before running
import java.nio.charset.Charset;
if ( !Charset.isSupported( sourceEncoding ) || !Charset.isSupported( targetEncoding ) ) {
  throw new IllegalArgumentException( "Unsupported charset" );
}

Try / catch

try {
  trans.execute( null );
} catch ( KettleException e ) {
  // CreatingFile wraps the real cause — inspect the chain
  Throwable cause = e.getCause();
  log.error( "Encoding conversion failed: {}", cause == null ? e : cause );
}

Prevention

When it happens

Trigger: In changeEncoding's try block: KettleVFS file creation/open of the target, reader/writer construction with unsupported charset names, IOExceptions during copy, or target file access problems — all funnel into this catch-all.

Common situations: Invalid encoding name typed in the dialog (e.g. 'utf8' vs 'UTF-8'); target file locked by another process; disk full; permission denied writing to target directory; source file being read while another step truncates it.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

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

Appendix: source

Thrown at plugins/core/impl/src/main/java/org/pentaho/di/trans/steps/changefileencoding/ChangeFileEncoding.java:243

        }
      }
      // add filename to result filenames?
      if ( meta.addTargetResultFilenames() ) {
        // Add this to the result file names...
        ResultFile resultFile =
            new ResultFile( ResultFile.FILE_TYPE_GENERAL,
                KettleVFS.getInstance( getTransMeta().getBowl() ).getFileObject( targetFilename ),
                getTransMeta().getName(), getStepname() );
        resultFile.setComment( BaseMessages.getString( PKG, "ChangeFileEncoding.Log.FileAddedResult" ) );
        addResultFile( resultFile );

        if ( isDetailed() ) {
          logDetailed( BaseMessages.getString( PKG, "ChangeFileEncoding.Log.FilenameAddResult", targetFilename ) );
        }
      }

    } catch ( Exception e ) {
      throw new KettleException( BaseMessages.getString( PKG, "ChangeFileEncoding.Error.CreatingFile" ), e );
    } finally {
      try {
        if ( buffWriter != null ) {
          buffWriter.flush();
          buffWriter.close();
        }
        if ( buffReader != null ) {
          buffReader.close();
        }
      } catch ( Exception e ) {
        // Ignore
      }
    }

  }

  public boolean init( StepMetaInterface smi, StepDataInterface sdi ) {
    meta = (ChangeFileEncodingMeta) smi;

View on GitHub (pinned to f3058517a1)