{"record":{"id":"ff6acad7bd693bf4","repo":"pentaho/pentaho-kettle","slug":"unexpected-null-vfs-filename","errorCode":null,"errorMessage":"Unexpected null VFS filename.","messagePattern":"Unexpected null VFS filename\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/pentaho/di/core/vfs/KettleVFSImpl.java","lineNumber":101,"sourceCode":"  }\n\n  // IMPORTANT:\n  // We have one problem with VFS: if the file is in a subdirectory of the current one: somedir/somefile\n  // In that case, VFS doesn't parse the file correctly.\n  // We need to put file: in front of it to make it work.\n  // However, how are we going to verify this?\n  //\n  // We are going to see if the filename starts with one of the known protocols like file: zip: ram: smb: jar: etc.\n  // If not, we are going to assume it's a file, when no scheme found ( flag as null ), and it only changes if\n  // a scheme is provided.\n  //\n  @Override\n  public FileObject getFileObject( String vfsFilename, VariableSpace space, FileSystemOptions fsOptions )\n    throws KettleFileException {\n\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  }","sourceCodeStart":83,"sourceCodeEnd":119,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/core/src/main/java/org/pentaho/di/core/vfs/KettleVFSImpl.java#L83-L119","documentation":"KettleVFSImpl.getFileObject validates its input and throws IllegalArgumentException(\"Unexpected null VFS filename.\") when the vfsFilename parameter is null. It is a defensive guard — commons-vfs would otherwise fail deeper with a less clear error — thrown before any filesystem access is attempted.","triggerScenarios":"Calling KettleVFS.getFileObject(null, space) or KettleVFSImpl.getFileObject(null, space, fsOptions); passing a null field value from a 'filename in field' configuration that resolved to null; a variable placeholder that expanded to nothing.","commonSituations":"A step's filename field containing a null row value; a variable like ${INPUT_FILE} not defined so it resolves to null; programmatic code building filenames dynamically where an earlier lookup returned null.","solutions":["Ensure the filename variable/field is defined and non-null before calling getFileObject.","If the filename comes from a row field, add a filter or default-value step for null rows.","Guard in code: skip or fail fast with a meaningful message when the resolved filename is null."],"exampleFix":"// before\nFileObject f = KettleVFS.getFileObject(variables.getVariable(\"INPUT_FILE\"), variables);\n// after\nString name = variables.getVariable(\"INPUT_FILE\");\nif (name == null || name.trim().isEmpty()) throw new KettleException(\"INPUT_FILE is not set\");\nFileObject f = KettleVFS.getFileObject(name, variables);","handlingStrategy":"type-guard","validationCode":"if (vfsFilename == null || vfsFilename.trim().isEmpty()) {\n  throw new KettleException(\"VFS filename must be provided\");\n}","typeGuard":"boolean isValidFilename(String s) { return s != null && !s.trim().isEmpty(); }","tryCatchPattern":"try {\n  fo = KettleVFS.getFileObject(name, space);\n} catch (IllegalArgumentException e) {\n  throw new KettleException(\"Input filename is null — check the variable/field feeding it\", e);\n}","preventionTips":["Define all filename variables with defaults in kettle.properties or step settings.","Filter out null rows when the filename comes from a row field.","Fail fast with explicit messages at configuration time."],"tags":["vfs","null","illegal-argument"],"backgroundTag":"null-argument","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"}