pentaho/pentaho-kettle · error · KettleVFSFileSystemException

ConnectionFileSystem.ExpectedConnectionNotFound

ConnectionFileSystem.ExpectedConnectionNotFound

Error message

ConnectionFileSystem.ExpectedConnectionNotFound

What it means

getExistingConnectionDetails calls manager.getExistingDetails(connectionName); a KettleException there is wrapped as ExpectedConnectionNotFound with the connection name. It means the named connection does not exist (or cannot be retrieved) in the ConnectionManager at the time of the pvfs:// resolution.

Solutions

1. Verify the connection name in the URL matches an existing connection in the connection manager
2. Create the missing connection or correct the name in the pvfs:// path
3. Check you are connected to the right repository/environment where the connection is defined
4. Wrap the cause KettleException to distinguish 'not found' from a lookup failure

Example fix

// before: URL references non-existent connection
FileObject f = KettleVFS.getFileObject("pvfs://prod-conn/data.csv");
// after: ensure the connection exists first
if (connectionManager.getExistingDetails("prod-conn") != null) {
  FileObject f = KettleVFS.getFileObject("pvfs://prod-conn/data.csv");
}

try { connectionManager.getExistingDetails(connName); } catch (KettleException e) { /* connection missing — create it or fail fast */ }

boolean connectionDefined = !manager.getDetails().stream().noneMatch(d -> d.getName().equals(connName));

try { resolvePvfs(connName); } catch (FileSystemException e) { if (causeCode == ExpectedConnectionNotFound) { createOrSelectConnection(); retry(); } }

When it happens

Trigger: Resolving or building a pvfs file name for a connection name that is not registered in the ConnectionManager — e.g. the connection was deleted, renamed, or never created in the current environment/repository.

Common situations: Hard-coded pvfs:// URLs referencing a connection that doesn't exist in the target environment; moving jobs between environments where connections are defined differently; connection deleted by another user/session.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• CustomVfsSettingsParser.Log.FailedToLoad
• FileSystemConfigBuilder could not parse parameter:
• Invalid repository type
• Only local files are supported at this time, file [
• ReportExportTask.PARENT_FOLDER_DOES_NOT_EXIST

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

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/connections/vfs/provider/ConnectionFileSystem.java:191

  // region Helpers
  @NonNull
  protected Bowl getBowl() {
    return KettleGenericFileSystemConfigBuilder.getInstance().getBowl( getFileSystemOptions() );
  }

  @NonNull
  protected IKettleVFS getKettleVFS() {
    return KettleVFS.getInstance( getBowl() );
  }

  @NonNull
  private VFSConnectionDetails getExistingConnectionDetails( @NonNull ConnectionManager manager, @NonNull String connectionName )
    throws KettleVFSFileSystemException {
    try {
      return manager.getExistingDetails( connectionName );
    } catch ( KettleException e ) {
      throw new KettleVFSFileSystemException( "ConnectionFileSystem.ExpectedConnectionNotFound", connectionName, e );
    }
  }

  @NonNull
  private VariableSpace initializeVariableSpace( @NonNull VFSConnectionDetails details )
    throws IOException {

    if ( details == null || details.getName() == null ) {
      throw new IOException( "Missing connection configuration" );
    }

    VariableSpace varSpace = getSpace();
    if ( varSpace == null ) {
      throw new IOException( "Failed to initialize connection variables" );
    }

    String connectionName = details.getName();

View on GitHub (pinned to f3058517a1)