{"record":{"id":"28dd37d95f14e206","repo":"pentaho/pentaho-kettle","slug":"connectionfileobject-connectionwithbucketsroot","errorCode":"ConnectionFileObject.ConnectionWithBucketsRoot.UnsupportedOperation","errorMessage":"ConnectionFileObject.ConnectionWithBucketsRoot.UnsupportedOperation","messagePattern":"ConnectionFileObject\\.ConnectionWithBucketsRoot\\.UnsupportedOperation","errorType":"exception","errorClass":"KettleVFSFileSystemException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/pentaho/di/connections/vfs/provider/ConnectionWithBucketsRootFileObject.java","lineNumber":45,"sourceCode":"/**\n * This class represents a file object for the connection root of an existing VFS connection which is using buckets,\n * as determined per {@link VFSConnectionManagerHelper#usesBuckets(VFSConnectionDetails)}.\n */\nclass ConnectionWithBucketsRootFileObject extends ConnectionFileObject {\n  public ConnectionWithBucketsRootFileObject( @NonNull ConnectionFileName name, @NonNull ConnectionFileSystem fs ) {\n    super( name, fs );\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(\n      \"ConnectionFileObject.ConnectionWithBucketsRoot.UnsupportedOperation\",\n      getName().getConnection() );\n  }\n\n  @Override\n  public FileType getType() throws FileSystemException {\n    return FileType.FOLDER;\n  }\n\n  @Override\n  public boolean isAttached() {\n    return true;\n  }\n\n  @Override\n  public boolean isExecutable() throws FileSystemException {\n    return false;\n  }","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/core/src/main/java/org/pentaho/di/connections/vfs/provider/ConnectionWithBucketsRootFileObject.java#L27-L63","documentation":"ConnectionWithBucketsRootFileObject represents the virtual root of a bucketed connection (e.g. S3 buckets). Its requireResolvedFileObject() override always throws KettleVFSFileSystemException with the connection name, because the root has no single resolved underlying file — callers must descend into a bucket first.","triggerScenarios":"Calling any operation that requires the concrete resolved file object directly on the connection-with-buckets root — e.g. reading/writing content, getting attributes on the root instead of a bucket child.","commonSituations":"Treating pvfs://myS3Conn (root) as if it were a readable folder/file; generic code that calls content APIs on every FileObject in a tree without skipping virtual roots.","solutions":["Resolve a specific bucket child (pvfs://myS3Conn/my-bucket/...) before performing file operations","Check getType() / connection capabilities before calling operations on the root","Skip bucket-root objects in generic file walkers that need resolved files","List the root's children to discover valid bucket names"],"exampleFix":"// before: operating on the root\nFileObject root = fs.resolveFile(\"pvfs://s3conn\");\nroot.getContent(); // throws\n// after\nFileObject bucket = fs.resolveFile(\"pvfs://s3conn/my-bucket/\");\nbucket.getContent();","handlingStrategy":"type-guard","validationCode":"FileObject target = name.endsWith(\"/\") || connRoot.equals(name) ? fo.resolveFile(bucketName + \"/\") : fo;","typeGuard":"boolean isBucketsRoot = fo instanceof ConnectionWithBucketsRootFileObject;","tryCatchPattern":"try { op(fo); } catch (FileSystemException e) { if (causeCode == UnsupportedOperation && isRoot(fo)) { fo = fo.resolveFile(\"my-bucket/\"); op(fo); } }","preventionTips":["Never read/write content on bucketed-connection roots","Descend into a bucket child before content operations","Check object type before generic content access in file walkers"],"tags":["vfs","unsupported-operation","virtual-root","buckets"],"backgroundTag":"unsupported-operation","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"}