pentaho/pentaho-kettle · error · KettleFileException

Unable to resolve file name for VFS URI '

Error message

Unable to resolve file name for VFS URI '

What it means

KettleVFSImpl.resolveURI parses a VFS URI string via FileSystemManager.resolveURI; any FileSystemException is wrapped in a KettleFileException with message "Unable to resolve file name for VFS URI '<cleansed URI>' : <cause>". Unlike getFileObject this deals with URI parsing, so failures usually mean the URI string is malformed rather than the file missing.

Solutions

1. URL-encode special characters in path and credentials (spaces, #, ?, @, :).
2. Check the chained FileSystemException for the exact parse error.
3. Use KettleVFS.normalizePath / getFriendlyURI helpers when building URIs programmatically.
4. Verify the scheme is registered with commons-vfs before resolving.

Example fix

// before
KettleVFS.getInstance().resolveURI("sftp://user:p@ss#word@host/my file.csv");
// after
KettleVFS.getInstance().resolveURI("sftp://user:p%40ss%23word@host/my%20file.csv");

// basic URI sanity before resolveURI
java.net.URI u = new java.net.URI(path.replace(' ', '_')); // throws URISyntaxException on bad syntax

try {
  fileName = KettleVFS.getInstance().resolveURI(vfsFilename);
} catch (KettleFileException e) {
  throw new KettleException("Malformed VFS URI: " + vfsFilename + " — check encoding", e);
}

When it happens

Trigger: Calling resolveURI (or APIs delegating to it) with a syntactically invalid VFS URI: bad scheme syntax, unescaped special characters, malformed authority (user:pass@host:port), or a URI the provider's parser rejects.

Common situations: Filenames containing spaces, '#', or '?' that weren't URL-encoded; passwords with special characters breaking the user:password@host form; empty scheme plus path colliding with VFS URI grammar.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• The function call deleteFile is not valid.
• The function call getFileExtension throw an error : +…
• The function call getLastModifiedTime throw an error : +…
• The function call getParentFoldername throw an error : +…
• vfs.provider/mismatched-fs-for-name.error

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

Appendix: source

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

        }
      }
    }

    return scheme;
  }

  @Override
  public FileName resolveURI( String vfsFilename ) throws KettleFileException {
    try {
      FileSystemManager fsManager = KettleVFS.getInstance().getFileSystemManager();

      // Make sure to wait for all providers to be loaded.
      getSchemeSafe( vfsFilename, fsManager );

      return fsManager.resolveURI( vfsFilename );

    } catch ( FileSystemException e ) {
      throw new KettleFileException( "Unable to resolve file name for VFS URI '"
        + KettleVFS.cleanseFilename( vfsFilename ) + "' : " + e.getMessage(), e );
    }
  }

  @Override
  public FileSystemOptions getFileSystemOptions( String scheme, String vfsFilename, VariableSpace space,
                                                  FileSystemOptions fileSystemOptions )
    throws IOException {
    if ( scheme == null ) {
      return fileSystemOptions;
    }

    return buildFsOptions( space, fileSystemOptions, vfsFilename, scheme );
  }

  private FileSystemOptions buildFsOptions( VariableSpace parentVariableSpace, FileSystemOptions sourceOptions,
                                            String vfsFilename, String scheme ) throws IOException {
    VariableSpace varSpace = parentVariableSpace;

View on GitHub (pinned to f3058517a1)