What causes "File not found" in pentaho/pentaho-kettle?

Verify the path exists (file.exists()) before the call, and correct typos/relative-path resolution

pentaho/pentaho-kettle · error · org.pentaho.di.core.exception.KettleFileNotFoundException

File not found

Error message

File not found

What it means

ValueDataUtil.throwsErrorOnFileNotFound pre-checks a Commons-VFS FileObject before file-based calculations (checksums, CRC32, Adler32, encoding detection, XML validation). If the file is null or does not exist it throws KettleFileNotFoundException carrying the path. It exists to fail fast with a clear message instead of a downstream FileSystemException.

Solutions

Verify the path exists (file.exists()) before the call, and correct typos/relative-path resolution
Check that the file is accessible from the machine executing the step (mounted volume, agent node)
Use a 'Check if file exists' step or earlier validation to skip missing files gracefully
Confirm correct case sensitivity for the target OS filesystem

Example fix

// before
Object crc = ValueDataUtil.checksumCRC32(meta, vfsFile); // file may not exist
// after
if (vfsFile != null && vfsFile.exists()) {
  Object crc = ValueDataUtil.checksumCRC32(meta, vfsFile);
} else {
  // skip or log missing file
}

Defensive patterns

Strategy: validation

Validate before calling

// Java (Commons VFS)
if (fileObject == null || !fileObject.exists()) {
  throw new FileNotFoundException(fileObject == null ? "<null>" : fileObject.getName().getPath());
}

Type guard

boolean isUsableFile(FileObject f) {
  try { return f != null && f.exists() && f.getType().hasChildren() != null; }
  catch (FileSystemException e) { return false; }
}

Try / catch

try {
  Object crc = ValueDataUtil.checksumCRC32(meta, file);
} catch (KettleFileNotFoundException e) {
  log.warn("Missing file: " + e.getMessage());
  // skip or default value
}

Prevention

Resolve paths against a configured base directory and validate at startup
Handle OS case-sensitivity differences (Linux vs Windows)
Use a 'Check if file exists' flow step before file-dependent calculations
Verify files are mounted/accessible on the node actually executing the step

When it happens

Trigger: Calling ValueDataUtil.createChecksum, checksumCRC32, checksumAdler32, loadFileContentInBinary, isXMLFileWellFormed, or getFileEncoding with a file path that is null-resolving or absent on the filesystem/VFS.

Common situations: Typos or wrong relative paths in a 'File exists/Checksum' step; file deleted between listing and processing; running on a node where the file is not mounted; case-sensitivity differences on Linux.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/core/row/ValueDataUtil.java:114

      round2Mode = ROUND_2_MODE_DEFAULT_VALUE;
      log.debug( "System property is omitted: ROUND_2_MODE. Default value used: " + SYS_PROPERTY_ROUND_2_MODE_DEFAULT_VALUE + "." );
    } else if ( SYS_PROPERTY_ROUND_2_MODE_DEFAULT_VALUE.equals( rpaValue ) ) {
      round2Mode = ROUND_2_MODE_DEFAULT_VALUE;
      log.debug( "System property read: ROUND_2_MODE=" + ROUND_2_MODE_DEFAULT_VALUE + " (default value)" );
    } else if ( SYS_PROPERTY_ROUND_2_MODE_BACKWARD_COMPATIBILITY_VALUE.equalsIgnoreCase( rpaValue ) ) {
      round2Mode = ROUND_2_MODE_BACKWARD_COMPATIBILITY_VALUE;
      log.debug( "System property read: ROUND_2_MODE=" + SYS_PROPERTY_ROUND_2_MODE_BACKWARD_COMPATIBILITY_VALUE
          + " (backward compatibility value)" );
    } else {
      log.warn( "Incorrect value of system property read: ROUND_2_MODE=" + rpaValue + ". Set to " + SYS_PROPERTY_ROUND_2_MODE_DEFAULT_VALUE
          + " instead." );
    }
    return round2Mode;
  }

  private static void throwsErrorOnFileNotFound( FileObject file ) throws KettleFileNotFoundException, FileSystemException {
    if ( file == null || !file.exists() ) {
      throw new KettleFileNotFoundException( "File not found", file.getName().getPath() );
    }
  }

  /**
   * @deprecated Use {@link Const#ltrim(String)} instead
   */
  @Deprecated
  public static final String leftTrim( String string ) {
    return Const.ltrim( string );
  }

  /**
   * @deprecated Use {@link Const#rtrim(String)} instead
   */
  @Deprecated
  public static final String rightTrim( String string ) {
    return Const.rtrim( string );
  }

View on GitHub (pinned to f3058517a1)