pentaho/pentaho-kettle · error · IllegalArgumentException

Unexpected null VFS filename.

Error message

Unexpected null VFS filename.

What it means

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.

Solutions

1. Ensure the filename variable/field is defined and non-null before calling getFileObject.
2. If the filename comes from a row field, add a filter or default-value step for null rows.
3. Guard in code: skip or fail fast with a meaningful message when the resolved filename is null.

Example fix

// before
FileObject f = KettleVFS.getFileObject(variables.getVariable("INPUT_FILE"), variables);
// after
String name = variables.getVariable("INPUT_FILE");
if (name == null || name.trim().isEmpty()) throw new KettleException("INPUT_FILE is not set");
FileObject f = KettleVFS.getFileObject(name, variables);

if (vfsFilename == null || vfsFilename.trim().isEmpty()) {
  throw new KettleException("VFS filename must be provided");
}

boolean isValidFilename(String s) { return s != null && !s.trim().isEmpty(); }

try {
  fo = KettleVFS.getFileObject(name, space);
} catch (IllegalArgumentException e) {
  throw new KettleException("Input filename is null — check the variable/field feeding it", e);
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Argument 'name' is not the PVFS root.
• Missing connection configuration
• Strings must not be null
• Unable to obtain a IUnifiedRepository instance
• URL cannot be null

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

Appendix: source

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

  }

  // IMPORTANT:
  // We have one problem with VFS: if the file is in a subdirectory of the current one: somedir/somefile
  // In that case, VFS doesn't parse the file correctly.
  // We need to put file: in front of it to make it work.
  // However, how are we going to verify this?
  //
  // We are going to see if the filename starts with one of the known protocols like file: zip: ram: smb: jar: etc.
  // If not, we are going to assume it's a file, when no scheme found ( flag as null ), and it only changes if
  // a scheme is provided.
  //
  @Override
  public FileObject getFileObject( String vfsFilename, VariableSpace space, FileSystemOptions fsOptions )
    throws KettleFileException {

    //  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 );
    }
  }

View on GitHub (pinned to f3058517a1)