pentaho/pentaho-kettle · error · IllegalArgumentException

Argument 'name' is not the PVFS root.

Error message

Argument 'name' is not the PVFS root.

What it means

PvfsRootFileObject's constructor is only valid for the virtual pvfs root; it asserts name.isPvfsRoot() and throws IllegalArgumentException otherwise. This is a programmer-error guard: the root file object class must not be instantiated for non-root pvfs names.

Solutions

1. Only pass names where name.isPvfsRoot() is true (bare 'pvfs://')
2. Let ConnectionFileSystem.createFile choose the file object class instead of constructing it manually
3. For non-root names use the appropriate ConnectionFileObject subclass
4. Add an isPvfsRoot() check before constructing

Example fix

// before
new PvfsRootFileObject(connFileName, fs); // connFileName has a connection
// after
if (connFileName.isPvfsRoot()) {
  new PvfsRootFileObject(connFileName, fs);
} else {
  fs.resolveFile(connFileName);
}

if (!fileName.isPvfsRoot()) { /* use ConnectionFileSystem.createFile or the right subclass instead */ }

boolean canBeRoot = fileName instanceof ConnectionFileName c && c.isPvfsRoot();

try { new PvfsRootFileObject(name, fs); } catch (IllegalArgumentException e) { /* route to fs.resolveFile(name) instead */ }

When it happens

Trigger: Directly constructing new PvfsRootFileObject(name, fs) with a ConnectionFileName that is not the pvfs root (has a connection/path portion).

Common situations: Custom code or subclasses instantiating root file objects manually; refactors that route non-root names to the wrong file object class instead of letting ConnectionFileSystem.createFile dispatch.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Must use the messageClass, props constructor
• The PVFS root must have a path of '/'.
• Unexpected null VFS filename.
• AbstractFileErrorHandler.Exception.CouldNotCreateFileErrorHandlerForFile
• Append file in repository is not possible

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

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/connections/vfs/provider/PvfsRootFileObject.java:33

package org.pentaho.di.connections.vfs.provider;

import edu.umd.cs.findbugs.annotations.NonNull;
import edu.umd.cs.findbugs.annotations.Nullable;
import org.apache.commons.vfs2.FileObject;
import org.apache.commons.vfs2.FileSystemException;
import org.apache.commons.vfs2.FileType;
import org.apache.commons.vfs2.provider.AbstractFileObject;
import org.pentaho.di.core.vfs.KettleVFSFileSystemException;

/**
 * This class represents a file object for the PVFS root.
 */
class PvfsRootFileObject extends ConnectionFileObject {
  public PvfsRootFileObject( @NonNull ConnectionFileName name, @NonNull ConnectionFileSystem fs ) {
    super( name, fs );

    if ( !name.isPvfsRoot() ) {
      throw new IllegalArgumentException( "Argument 'name' is not the PVFS root." );
    }
  }

  @Override
  @Nullable
  public FileObject getResolvedFileObject() {
    return null;
  }

  @Override
  @NonNull
  protected AbstractFileObject<?> requireResolvedFileObject() throws FileSystemException {
    throw new KettleVFSFileSystemException( "ConnectionFileObject.PVFSRoot.UnsupportedOperation" );
  }

  @Override
  public FileType getType() throws FileSystemException {
    return FileType.FOLDER;

View on GitHub (pinned to f3058517a1)