pentaho/pentaho-kettle · error · KettleFileException

Unable to get VFS File object for filename '

Error message

Unable to get VFS File object for filename '

What it means

KettleVFSImpl.getFileObject resolves the (normalized) filename through the commons-vfs FileSystemManager; any IOException during resolution is wrapped in a KettleFileException with message "Unable to get VFS File object for filename '<cleansed name>' : <cause>". The filename is cleansed (credentials stripped) before inclusion in the message. This indicates VFS could not resolve the file — usually it doesn't exist, the scheme/provider is missing, or authentication/network failed.

Solutions

1. Read the chained cause message to see the underlying resolve error (does not exist / unknown host / auth failed).
2. Verify the file actually exists at the given path and that the scheme is spelled correctly.
3. For sftp/ftp, check credentials and host reachability (ping / ssh test).
4. Ensure the corresponding commons-vfs provider jar/plugin for the scheme is on the classpath.
5. Use KettleVFS.fileExists() to check existence before resolving when appropriate.

Example fix

// before
FileObject f = KettleVFS.getFileObject("sftp://user@badhost/data.csv", space);
// after
if (!KettleVFS.fileExists("sftp://user@correcthost/data.csv", space)) {
  throw new KettleException("Input file missing: sftp://user@correcthost/data.csv");
}
FileObject f = KettleVFS.getFileObject("sftp://user@correcthost/data.csv", space);

if (!KettleVFS.fileExists(path, space)) {
  throw new KettleException("File does not exist: " + path);
}

try {
  fo = KettleVFS.getFileObject(path, space);
} catch (KettleFileException e) {
  log.error("Cannot resolve " + path + ": " + e.getCause(), e); // cause shows does-not-exist vs auth vs network
  throw e;
}

When it happens

Trigger: Calling getFileObject with a path whose provider can't resolve it: nonexistent local file when the scheme requires existence, wrong host/port for sftp/http, invalid credentials, unknown scheme (no provider plugin), or network failure during resolveFile.

Common situations: Typo in path or scheme (htp:// instead of http://); SFTP server unreachable or key-based auth misconfigured; reading a file that another process deleted; missing VFS plugin for the requested scheme.

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

• The function call getShortFilename throw an error : +…
• The function call isFolder throw an error : + e.toString()
• AvroInput.Error.SchemaError
• ChangeFileEncoding.Error.SourceFileNotExists
• Error opening new file

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

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/core/vfs/KettleVFSImpl.java:116

    //  Protect the code below from invalid input.
    if ( vfsFilename == null ) {
      throw new IllegalArgumentException( "Unexpected null VFS filename." );
    }

    try {
      FileSystemManager fsManager = KettleVFS.getInstance().getFileSystemManager();

      String scheme = getSchemeSafe( vfsFilename, fsManager );

      fsOptions = getFileSystemOptions( scheme, vfsFilename, space, fsOptions );

      String filename = KettleVFS.normalizePath( vfsFilename, scheme );

      return fsOptions != null ? fsManager.resolveFile( filename, fsOptions ) : fsManager.resolveFile( filename );

    } catch ( IOException e ) {
      throw new KettleFileException( "Unable to get VFS File object for filename '"
        + KettleVFS.cleanseFilename( vfsFilename ) + "' : " + e.getMessage(), e );
    }
  }

  private static String getSchemeSafe( String vfsFilename, FileSystemManager fsManager ) {
    String[] schemes = fsManager.getSchemes();

    String scheme = KettleVFS.getScheme( schemes, vfsFilename );

    //Waiting condition - PPP-4374:
    //We have to check for hasScheme even if scheme is null because that scheme could not
    //be available by getScheme at the time we validate our scheme flag ( Kitchen loading problem )
    //So we check if - even it has not a scheme - our vfsFilename has a possible scheme format (PROVIDER_PATTERN_SCHEME)
    //If it does, then give it some time and tries to load. It stops when timeout is up or a scheme is found.
    int timeOut = TIMEOUT_LIMIT;
    if ( KettleVFS.hasSchemePattern( vfsFilename, KettleVFS.PROVIDER_PATTERN_SCHEME ) ) {
      while (scheme == null && timeOut > 0) {
        // ask again to refresh schemes list

View on GitHub (pinned to f3058517a1)