pentaho/pentaho-kettle · error · IOException

Failed to initialize connection variables

Error message

Failed to initialize connection variables

What it means

After validating details, initializeVariableSpace fetches the base VariableSpace via getSpace(); if it returns null the code throws IOException 'Failed to initialize connection variables'. The variable space is needed to expose the CONNECTION variable consumed by KettleVFSImpl#buildFsOptions / VFSHelper#getOpts.

Solutions

1. Call KettleEnvironment.init() (which initializes the variable space) before resolving pvfs files
2. Ensure the ConnectionFileSystem is constructed with a valid variable space supplier
3. In tests, initialize a Variables/KettleEnvironment instance before creating the filesystem
4. Check for shutdown code that nulls the space before VFS usage completes

Example fix

// before
ConnectionFileSystem fs = new ConnectionFileSystem(...); // no env init
// after
KettleEnvironment.init();
ConnectionFileSystem fs = new ConnectionFileSystem(...);

if (KettleEnvironment.isInitialized() == false) KettleEnvironment.init(); // ensure variable space exists

try { fo = fs.resolveFile(url); } catch (IOException e) { if ("Failed to initialize connection variables".equals(e.getMessage())) { KettleEnvironment.init(); retry(); } }

When it happens

Trigger: createFile or toPvfsFileName -> initializeVariableSpace when the filesystem's variable space source (getSpace()) returns null — typically the Kettle variable environment was never initialized or the space supplier is unwired.

Common situations: Using pvfs VFS in embedded/headless contexts without KettleEnvironment.init(); tests that instantiate the filesystem directly without a variable space; variable space cleared during shutdown.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• ConnectionFileProvider.FailedLoadConnectionManager
• Error initialize repo:// VFS
• FileSystemConfigBuilder could not parse parameter:
• Unable to obtain a IUnifiedRepository instance
• AbstractFileErrorHandler.Exception.CouldNotCreateFileErrorHandlerForFile

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

Appendix: source

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

    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();

    // Used by KettleVFSImpl#buildFsOptions -> VFSHelper#getOpts(...).
    varSpace.setVariable( CONNECTION, connectionName );

    details.setSpace( varSpace );

    return varSpace;
  }

  @NonNull
  protected VariableSpace getSpace() throws IOException {
    VariableSpace varSpace = (VariableSpace) getConfigBuilder().getVariableSpace( getFileSystemOptions() );
    return varSpace != null ? varSpace : Variables.getADefaultVariableSpace();
  }

View on GitHub (pinned to f3058517a1)