What causes "The PVFS root must have a path of '/'." in pentaho/pentaho-kettle?

Pass a non-empty connection name as the first constructor argument.

pentaho/pentaho-kettle · error · IllegalArgumentException

The PVFS root must have a path of '/'.

Error message

The PVFS root must have a path of '/'.

What it means

ConnectionFileName represents a pvfs:// name for a named VFS connection. A file name that has no connection segment (connection is null/empty) can only be the PVFS root itself, whose path must be '/'. Anything else would be an unattached path with no owning connection, so an IllegalArgumentException is thrown at construction time.

Solutions

Pass a non-empty connection name as the first constructor argument.
If you truly want the root, use path '/' with FileType.FOLDER: new ConnectionFileName(null, "/", FileType.FOLDER).
Fix the upstream parsing so the connection segment is preserved in the absolute path.
Ensure the connection name isn't emptied by earlier normalization/trimming of the details.

Example fix

// before
new ConnectionFileName( "", "folder/file.txt", FileType.FILE );
// after
new ConnectionFileName( "my-connection", "folder/file.txt", FileType.FILE );

Defensive patterns

Strategy: validation

Validate before calling

if ( StringUtils.isEmpty( connection ) && !"/".equals( absPath ) ) {
  throw new IllegalArgumentException( "Provide a connection name, or use path '/' for the root" );
}

Type guard

null

Try / catch

try {
  ConnectionFileName name = new ConnectionFileName( connection, absPath, type );
} catch ( IllegalArgumentException e ) {
  // add the connection segment and rebuild
}

Prevention

Never build pvfs names with an empty connection unless creating the root
Centralize ConnectionFileName construction in one factory that validates inputs
Verify parser output preserves the connection segment

When it happens

Trigger: Constructing new ConnectionFileName(null-or-empty, absPath, type) with absPath not equal to '/' — e.g. new ConnectionFileName("", "folder/file.txt", FileType.FILE) — or a parser producing a name where the connection segment was stripped but a deeper path remains.

Common situations: Building PVFS names by hand without the connection segment; URI parsing that drops the connection part; re-rooting names under a connection whose name is empty because the details were unnamed.

Related errors

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

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/connections/vfs/provider/ConnectionFileName.java:39

import org.apache.commons.vfs2.provider.AbstractFileName;

import java.util.Objects;

public class ConnectionFileName extends AbstractFileName {

  @Nullable
  private String connection;

  public ConnectionFileName( @Nullable String connection ) {
    this( connection, SEPARATOR, FileType.FOLDER );
  }

  public ConnectionFileName( @Nullable String connection, @Nullable String absPath, @NonNull FileType type ) {
    super( ConnectionFileProvider.SCHEME, absPath, type );
    this.connection = StringUtils.isEmpty( connection ) ? null : connection;

    if ( this.connection == null && !SEPARATOR.equals( getPath() ) ) {
      throw new IllegalArgumentException( "The PVFS root must have a path of '/'." );
    }
  }

  @Override
  public ConnectionFileName createName( String absPath, FileType type ) {
    return new ConnectionFileName( connection, absPath, type );
  }

  public ConnectionFileName createChildName( String name, FileType type ) {
    String childAbsPath = getConnectionFileNameUtils().ensureTrailingSeparator( getPath() ) + name;
    return new ConnectionFileName( connection, childAbsPath, type );
  }

  @NonNull
  protected ConnectionFileNameUtils getConnectionFileNameUtils() {
    // Seems overkill to store in an instance field solely for being unit test injection.
    return ConnectionFileNameUtils.getInstance();
  }

View on GitHub (pinned to f3058517a1)