{"record":{"id":"afdcef32d0f0ac0a","repo":"pentaho/pentaho-kettle","slug":"unable-to-get-vfs-file-object-for-filename","errorCode":null,"errorMessage":"Unable to get VFS File object for filename '","messagePattern":"Unable to get VFS File object for filename '","errorType":"exception","errorClass":"KettleFileException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/pentaho/di/core/vfs/KettleVFSImpl.java","lineNumber":116,"sourceCode":"\n    //  Protect the code below from invalid input.\n    if ( vfsFilename == null ) {\n      throw new IllegalArgumentException( \"Unexpected null VFS filename.\" );\n    }\n\n    try {\n      FileSystemManager fsManager = KettleVFS.getInstance().getFileSystemManager();\n\n      String scheme = getSchemeSafe( vfsFilename, fsManager );\n\n      fsOptions = getFileSystemOptions( scheme, vfsFilename, space, fsOptions );\n\n      String filename = KettleVFS.normalizePath( vfsFilename, scheme );\n\n      return fsOptions != null ? fsManager.resolveFile( filename, fsOptions ) : fsManager.resolveFile( filename );\n\n    } catch ( IOException e ) {\n      throw new KettleFileException( \"Unable to get VFS File object for filename '\"\n        + KettleVFS.cleanseFilename( vfsFilename ) + \"' : \" + e.getMessage(), e );\n    }\n  }\n\n  private static String getSchemeSafe( String vfsFilename, FileSystemManager fsManager ) {\n    String[] schemes = fsManager.getSchemes();\n\n    String scheme = KettleVFS.getScheme( schemes, vfsFilename );\n\n    //Waiting condition - PPP-4374:\n    //We have to check for hasScheme even if scheme is null because that scheme could not\n    //be available by getScheme at the time we validate our scheme flag ( Kitchen loading problem )\n    //So we check if - even it has not a scheme - our vfsFilename has a possible scheme format (PROVIDER_PATTERN_SCHEME)\n    //If it does, then give it some time and tries to load. It stops when timeout is up or a scheme is found.\n    int timeOut = TIMEOUT_LIMIT;\n    if ( KettleVFS.hasSchemePattern( vfsFilename, KettleVFS.PROVIDER_PATTERN_SCHEME ) ) {\n      while (scheme == null && timeOut > 0) {\n        // ask again to refresh schemes list","sourceCodeStart":98,"sourceCodeEnd":134,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/core/src/main/java/org/pentaho/di/core/vfs/KettleVFSImpl.java#L98-L134","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the chained cause message to see the underlying resolve error (does not exist / unknown host / auth failed).","Verify the file actually exists at the given path and that the scheme is spelled correctly.","For sftp/ftp, check credentials and host reachability (ping / ssh test).","Ensure the corresponding commons-vfs provider jar/plugin for the scheme is on the classpath.","Use KettleVFS.fileExists() to check existence before resolving when appropriate."],"exampleFix":"// before\nFileObject f = KettleVFS.getFileObject(\"sftp://user@badhost/data.csv\", space);\n// after\nif (!KettleVFS.fileExists(\"sftp://user@correcthost/data.csv\", space)) {\n  throw new KettleException(\"Input file missing: sftp://user@correcthost/data.csv\");\n}\nFileObject f = KettleVFS.getFileObject(\"sftp://user@correcthost/data.csv\", space);","handlingStrategy":"try-catch","validationCode":"if (!KettleVFS.fileExists(path, space)) {\n  throw new KettleException(\"File does not exist: \" + path);\n}","typeGuard":null,"tryCatchPattern":"try {\n  fo = KettleVFS.getFileObject(path, space);\n} catch (KettleFileException e) {\n  log.error(\"Cannot resolve \" + path + \": \" + e.getCause(), e); // cause shows does-not-exist vs auth vs network\n  throw e;\n}","preventionTips":["Always fileExists()-check paths that may be missing.","Test sftp/ftp connectivity and credentials outside Kettle first.","Confirm required VFS provider plugins are installed for exotic schemes."],"tags":["vfs","file-not-found","io","network"],"backgroundTag":"file-not-found","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"}