{"record":{"id":"1ec10c5e3cf78dce","repo":"pentaho/pentaho-kettle","slug":"unable-to-obtain-a-iunifiedrepository-instance","errorCode":null,"errorMessage":"Unable to obtain a IUnifiedRepository instance","messagePattern":"Unable to obtain a IUnifiedRepository instance","errorType":"exception","errorClass":"FileSystemException","httpStatus":null,"severity":"critical","filePath":"plugins/repo-vfs/repo-vfs-pur/src/main/java/org/pentaho/di/plugins/repofvs/pur/vfs/PurFileSystem.java","lineNumber":46,"sourceCode":"import org.apache.commons.vfs2.provider.AbstractFileSystem;\nimport org.slf4j.Logger;\nimport org.slf4j.LoggerFactory;\n\npublic class PurFileSystem extends AbstractFileSystem {\n\n  private static final Logger log = LoggerFactory.getLogger( PurFileSystem.class );\n\n  private final IUnifiedRepository repo;\n  private final IRepositoryContentConverterHandler contentHandler;\n  private final Optional<OutputConverter> outputConverter;\n\n  PurFileSystem( FileName rootName, FileSystemOptions fileSystemOptions, RepositoryAccess repoAccess ) throws FileSystemException {\n    super( rootName, null, fileSystemOptions );\n    this.repo = repoAccess.getPur();\n    this.contentHandler = repoAccess.getContentHandler();\n    this.outputConverter = repoAccess.getOutputConverter();\n    if ( this.repo == null ) {\n       throw new FileSystemException( \"Unable to obtain a IUnifiedRepository instance\" );\n    }\n    log.debug( \"Unified repository VFS created ({})\", new PurFileSystemConfig( fileSystemOptions ).isRemote() ?\n      \"remote client\" : \"local server\" );\n  }\n\n  @Override\n  protected void addCapabilities( Collection<Capability> caps ) {\n    caps.addAll( PurProvider.capabilities );\n  }\n\n  @Override\n  protected PurFileObject createFile( AbstractFileName name ) throws Exception {\n    log.debug( \"FS.createFile: {}\", name );\n    String path = name.getPath();\n    RepositoryFile repoFile = repo.getFile( path );\n    if ( repoFile == null ) {\n      repoFile = new RepositoryFile.Builder( name.getBaseName() ).path( path ).build();\n    }","sourceCodeStart":28,"sourceCodeEnd":64,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/plugins/repo-vfs/repo-vfs-pur/src/main/java/org/pentaho/di/plugins/repofvs/pur/vfs/PurFileSystem.java#L28-L64","documentation":"PurFileSystem's constructor obtains the IUnifiedRepository from RepositoryAccess and throws a FileSystemException if it is null. Without a repository client the whole VFS filesystem cannot function, so construction fails fast.","triggerScenarios":"Constructing PurFileSystem with a RepositoryAccess whose getPur() returns null - e.g. PUR connection not established, missing repository configuration, or failed login before VFS setup.","commonSituations":"Missing/incorrect repository connection settings in kettle.properties or VFS options; repository plugin not initialized; local server (jackrabbit) not started when isRemote() is false; DI server unavailable for remote clients.","solutions":["Initialize the repository connection (login) before creating the PurFileSystem and ensure RepositoryAccess.getPur() returns a non-null IUnifiedRepository","Check repository configuration (URL, credentials) in the PUR/VFS options","If using a local server, verify the embedded jackrabbit repository started successfully and check its logs","Reconnect/re-login to the repository and retry filesystem construction"],"exampleFix":"// before\nRepositoryAccess access = new RepositoryAccess(); // getPur() == null\nFileSystem fs = new PurFileSystem( rootName, opts, access );\n// after\nIUnifiedRepository pur = connectAndLogin( cfg ); // non-null\nRepositoryAccess access = new RepositoryAccess( pur, contentHandler, outputConverter );\nFileSystem fs = new PurFileSystem( rootName, opts, access );","handlingStrategy":"validation","validationCode":"// Before building the filesystem, verify the repository is connected\nIUnifiedRepository pur = repoAccess.getPur();\nif ( pur == null ) {\n  throw new IllegalStateException( \"Connect/login to the repository before creating PurFileSystem\" );\n}","typeGuard":"boolean repositoryReady( RepositoryAccess ra ) {\n  return ra != null && ra.getPur() != null && ra.getContentHandler() != null;\n}","tryCatchPattern":"try {\n  FileSystem fs = new PurFileSystem( rootName, opts, repoAccess );\n} catch ( FileSystemException e ) {\n  if ( String.valueOf( e.getMessage() ).contains( \"IUnifiedRepository\" ) ) {\n    repoAccess.login(); // reconnect then retry\n    fs = new PurFileSystem( rootName, opts, repoAccess );\n  }\n}","preventionTips":["Always establish the PUR connection (login) before VFS construction","Validate repository configuration (URL, credentials) at startup","For local mode, confirm the embedded jackrabbit server started","Wrap VFS construction with a connectivity check and clear startup error"],"tags":["vfs","repository","initialization","null"],"backgroundTag":"missing-dependency","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"}