pentaho/pentaho-kettle · error · KettleException

ChangeFileEncoding.Error.SourceFileNotAFile

ChangeFileEncoding.Error.SourceFileNotAFile

Error message

ChangeFileEncoding.Error.SourceFileNotAFile

What it means

After confirming the source path exists, the step checks that it is a regular file (VFS FileType.FILE). If the path is a directory, symlink to a folder, or other non-file resource, this KettleException is thrown with the path in the message. File encoding conversion only applies to regular files.

Solutions

  1. Point the source filename at the individual file, not a directory.
  2. Pre-process the directory with a 'Get File Names' step to enumerate files and loop over them.
  3. Verify the path in the message is not a directory: test -d '<path>'.

Example fix

// before
// source filename field contains: /data/incoming
// after: use Get File Names step to list files, pass /data/incoming/data.txt
Defensive patterns

Strategy: validation

Validate before calling

import java.io.File;
File p = new File( resolvedSourcePath );
if ( p.exists() && !p.isFile() ) {
  throw new IllegalArgumentException( "Path is not a regular file: " + p );
}

Prevention

When it happens

Trigger: In processRow: if (data.sourceFile.getType() != FileType.FILE) throw — the existing source path is a directory or other non-file VFS resource.

Common situations: The filename field accidentally contains a directory path; a glob was expected to expand but the literal directory name was passed; the user pointed the step at a mount point or a folder of files instead of a single file.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

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

Appendix: source

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

      // get target filename
      String targetFilename = data.inputRowMeta.getString( outputRow, data.indexOfTargetFileename );
      if ( Utils.isEmpty( targetFilename ) ) {
        throw new KettleException( BaseMessages.getString( PKG, "ChangeFileEncoding.Error.TargetFileIsEmpty",
          meta.getTargetFilenameField() ) );
      }

      data.sourceFile = KettleVFS.getInstance( getTransMeta().getBowl() ).getFileObject( sourceFilename );

      // Check if source file exists
      if ( !data.sourceFile.exists() ) {
        throw new KettleException(
            BaseMessages.getString( PKG, "ChangeFileEncoding.Error.SourceFileNotExists", sourceFilename ) );
      }

      // Check if source file is a file
      if ( data.sourceFile.getType() != FileType.FILE ) {
        throw new KettleException(
            BaseMessages.getString( PKG, "ChangeFileEncoding.Error.SourceFileNotAFile", sourceFilename ) );
      }

      // create directory only if not exists
      if ( !data.sourceFile.getParent().exists() ) {
        if ( meta.isCreateParentFolder() ) {
          data.sourceFile.getParent().createFolder();
        } else {
          throw new KettleException( BaseMessages.getString( PKG, "ChangeFileEncoding.Error.ParentFolderNotExist",
            data.sourceFile.getParent().toString() ) );
        }
      }

      // Change file encoding
      changeEncoding( sourceFilename, targetFilename );

      putRow( data.inputRowMeta, outputRow ); // copy row to output rowset(s);

View on GitHub (pinned to f3058517a1)