{"record":{"id":"7ccb0948dd242676","repo":"pentaho/pentaho-kettle","slug":"argument-name-is-not-the-pvfs-root","errorCode":null,"errorMessage":"Argument 'name' is not the PVFS root.","messagePattern":"Argument 'name' is not the PVFS root\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/pentaho/di/connections/vfs/provider/PvfsRootFileObject.java","lineNumber":33,"sourceCode":"package org.pentaho.di.connections.vfs.provider;\n\nimport edu.umd.cs.findbugs.annotations.NonNull;\nimport edu.umd.cs.findbugs.annotations.Nullable;\nimport org.apache.commons.vfs2.FileObject;\nimport org.apache.commons.vfs2.FileSystemException;\nimport org.apache.commons.vfs2.FileType;\nimport org.apache.commons.vfs2.provider.AbstractFileObject;\nimport org.pentaho.di.core.vfs.KettleVFSFileSystemException;\n\n/**\n * This class represents a file object for the PVFS root.\n */\nclass PvfsRootFileObject extends ConnectionFileObject {\n  public PvfsRootFileObject( @NonNull ConnectionFileName name, @NonNull ConnectionFileSystem fs ) {\n    super( name, fs );\n\n    if ( !name.isPvfsRoot() ) {\n      throw new IllegalArgumentException( \"Argument 'name' is not the PVFS root.\" );\n    }\n  }\n\n  @Override\n  @Nullable\n  public FileObject getResolvedFileObject() {\n    return null;\n  }\n\n  @Override\n  @NonNull\n  protected AbstractFileObject<?> requireResolvedFileObject() throws FileSystemException {\n    throw new KettleVFSFileSystemException( \"ConnectionFileObject.PVFSRoot.UnsupportedOperation\" );\n  }\n\n  @Override\n  public FileType getType() throws FileSystemException {\n    return FileType.FOLDER;","sourceCodeStart":15,"sourceCodeEnd":51,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/core/src/main/java/org/pentaho/di/connections/vfs/provider/PvfsRootFileObject.java#L15-L51","documentation":"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.","triggerScenarios":"Directly constructing new PvfsRootFileObject(name, fs) with a ConnectionFileName that is not the pvfs root (has a connection/path portion).","commonSituations":"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.","solutions":["Only pass names where name.isPvfsRoot() is true (bare 'pvfs://')","Let ConnectionFileSystem.createFile choose the file object class instead of constructing it manually","For non-root names use the appropriate ConnectionFileObject subclass","Add an isPvfsRoot() check before constructing"],"exampleFix":"// before\nnew PvfsRootFileObject(connFileName, fs); // connFileName has a connection\n// after\nif (connFileName.isPvfsRoot()) {\n  new PvfsRootFileObject(connFileName, fs);\n} else {\n  fs.resolveFile(connFileName);\n}","handlingStrategy":"validation","validationCode":"if (!fileName.isPvfsRoot()) { /* use ConnectionFileSystem.createFile or the right subclass instead */ }","typeGuard":"boolean canBeRoot = fileName instanceof ConnectionFileName c && c.isPvfsRoot();","tryCatchPattern":"try { new PvfsRootFileObject(name, fs); } catch (IllegalArgumentException e) { /* route to fs.resolveFile(name) instead */ }","preventionTips":["Let ConnectionFileSystem.createFile dispatch file object classes","Only construct PvfsRootFileObject for bare pvfs:// names","Add isPvfsRoot assertions in custom provider code"],"tags":["vfs","illegal-argument","constructor","invariant"],"backgroundTag":"invalid-argument-value","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"}