pentaho/pentaho-kettle · critical · FileSystemException

Unable to obtain a IUnifiedRepository instance

Error message

Unable to obtain a IUnifiedRepository instance

What it means

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.

Solutions

1. Initialize the repository connection (login) before creating the PurFileSystem and ensure RepositoryAccess.getPur() returns a non-null IUnifiedRepository
2. Check repository configuration (URL, credentials) in the PUR/VFS options
3. If using a local server, verify the embedded jackrabbit repository started successfully and check its logs
4. Reconnect/re-login to the repository and retry filesystem construction

Example fix

// before
RepositoryAccess access = new RepositoryAccess(); // getPur() == null
FileSystem fs = new PurFileSystem( rootName, opts, access );
// after
IUnifiedRepository pur = connectAndLogin( cfg ); // non-null
RepositoryAccess access = new RepositoryAccess( pur, contentHandler, outputConverter );
FileSystem fs = new PurFileSystem( rootName, opts, access );

// Before building the filesystem, verify the repository is connected
IUnifiedRepository pur = repoAccess.getPur();
if ( pur == null ) {
  throw new IllegalStateException( "Connect/login to the repository before creating PurFileSystem" );
}

boolean repositoryReady( RepositoryAccess ra ) {
  return ra != null && ra.getPur() != null && ra.getContentHandler() != null;
}

try {
  FileSystem fs = new PurFileSystem( rootName, opts, repoAccess );
} catch ( FileSystemException e ) {
  if ( String.valueOf( e.getMessage() ).contains( "IUnifiedRepository" ) ) {
    repoAccess.login(); // reconnect then retry
    fs = new PurFileSystem( rootName, opts, repoAccess );
  }
}

When it happens

Trigger: Constructing PurFileSystem with a RepositoryAccess whose getPur() returns null - e.g. PUR connection not established, missing repository configuration, or failed login before VFS setup.

Common situations: 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.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• Error initialize repo:// VFS
• Append file in repository is not possible
• ConnectionFileProvider.FailedLoadConnectionManager
• Failed to initialize connection variables
• Invalid repository type

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

Appendix: source

Thrown at plugins/repo-vfs/repo-vfs-pur/src/main/java/org/pentaho/di/plugins/repofvs/pur/vfs/PurFileSystem.java:46

import org.apache.commons.vfs2.provider.AbstractFileSystem;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class PurFileSystem extends AbstractFileSystem {

  private static final Logger log = LoggerFactory.getLogger( PurFileSystem.class );

  private final IUnifiedRepository repo;
  private final IRepositoryContentConverterHandler contentHandler;
  private final Optional<OutputConverter> outputConverter;

  PurFileSystem( FileName rootName, FileSystemOptions fileSystemOptions, RepositoryAccess repoAccess ) throws FileSystemException {
    super( rootName, null, fileSystemOptions );
    this.repo = repoAccess.getPur();
    this.contentHandler = repoAccess.getContentHandler();
    this.outputConverter = repoAccess.getOutputConverter();
    if ( this.repo == null ) {
       throw new FileSystemException( "Unable to obtain a IUnifiedRepository instance" );
    }
    log.debug( "Unified repository VFS created ({})", new PurFileSystemConfig( fileSystemOptions ).isRemote() ?
      "remote client" : "local server" );
  }

  @Override
  protected void addCapabilities( Collection<Capability> caps ) {
    caps.addAll( PurProvider.capabilities );
  }

  @Override
  protected PurFileObject createFile( AbstractFileName name ) throws Exception {
    log.debug( "FS.createFile: {}", name );
    String path = name.getPath();
    RepositoryFile repoFile = repo.getFile( path );
    if ( repoFile == null ) {
      repoFile = new RepositoryFile.Builder( name.getBaseName() ).path( path ).build();
    }

View on GitHub (pinned to f3058517a1)