{"record":{"id":"47701820a391b215","repo":"pentaho/pentaho-kettle","slug":"unable-to-resolve-file-name-for-vfs-uri","errorCode":null,"errorMessage":"Unable to resolve file name for VFS URI '","messagePattern":"Unable to resolve file name for VFS URI '","errorType":"exception","errorClass":"KettleFileException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/pentaho/di/core/vfs/KettleVFSImpl.java","lineNumber":161,"sourceCode":"        }\n      }\n    }\n\n    return scheme;\n  }\n\n  @Override\n  public FileName resolveURI( String vfsFilename ) throws KettleFileException {\n    try {\n      FileSystemManager fsManager = KettleVFS.getInstance().getFileSystemManager();\n\n      // Make sure to wait for all providers to be loaded.\n      getSchemeSafe( vfsFilename, fsManager );\n\n      return fsManager.resolveURI( vfsFilename );\n\n    } catch ( FileSystemException e ) {\n      throw new KettleFileException( \"Unable to resolve file name for VFS URI '\"\n        + KettleVFS.cleanseFilename( vfsFilename ) + \"' : \" + e.getMessage(), e );\n    }\n  }\n\n  @Override\n  public FileSystemOptions getFileSystemOptions( String scheme, String vfsFilename, VariableSpace space,\n                                                  FileSystemOptions fileSystemOptions )\n    throws IOException {\n    if ( scheme == null ) {\n      return fileSystemOptions;\n    }\n\n    return buildFsOptions( space, fileSystemOptions, vfsFilename, scheme );\n  }\n\n  private FileSystemOptions buildFsOptions( VariableSpace parentVariableSpace, FileSystemOptions sourceOptions,\n                                            String vfsFilename, String scheme ) throws IOException {\n    VariableSpace varSpace = parentVariableSpace;","sourceCodeStart":143,"sourceCodeEnd":179,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/core/src/main/java/org/pentaho/di/core/vfs/KettleVFSImpl.java#L143-L179","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["URL-encode special characters in path and credentials (spaces, #, ?, @, :).","Check the chained FileSystemException for the exact parse error.","Use KettleVFS.normalizePath / getFriendlyURI helpers when building URIs programmatically.","Verify the scheme is registered with commons-vfs before resolving."],"exampleFix":"// before\nKettleVFS.getInstance().resolveURI(\"sftp://user:p@ss#word@host/my file.csv\");\n// after\nKettleVFS.getInstance().resolveURI(\"sftp://user:p%40ss%23word@host/my%20file.csv\");","handlingStrategy":"validation","validationCode":"// basic URI sanity before resolveURI\njava.net.URI u = new java.net.URI(path.replace(' ', '_')); // throws URISyntaxException on bad syntax","typeGuard":null,"tryCatchPattern":"try {\n  fileName = KettleVFS.getInstance().resolveURI(vfsFilename);\n} catch (KettleFileException e) {\n  throw new KettleException(\"Malformed VFS URI: \" + vfsFilename + \" — check encoding\", e);\n}","preventionTips":["URL-encode spaces and special characters in paths and passwords.","Build URIs programmatically instead of string concatenation.","Validate user-supplied URI patterns at configuration time."],"tags":["vfs","uri","malformed-url"],"backgroundTag":"invalid-url-format","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}