{"record":{"id":"6102cbb1427a8641","repo":"pentaho/pentaho-kettle","slug":"failed-to-initialize-connection-variables","errorCode":null,"errorMessage":"Failed to initialize connection variables","messagePattern":"Failed to initialize connection variables","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/pentaho/di/connections/vfs/provider/ConnectionFileSystem.java","lineNumber":205,"sourceCode":"    throws KettleVFSFileSystemException {\n    try {\n      return manager.getExistingDetails( connectionName );\n    } catch ( KettleException e ) {\n      throw new KettleVFSFileSystemException( \"ConnectionFileSystem.ExpectedConnectionNotFound\", connectionName, e );\n    }\n  }\n\n  @NonNull\n  private VariableSpace initializeVariableSpace( @NonNull VFSConnectionDetails details )\n    throws IOException {\n\n    if ( details == null || details.getName() == null ) {\n      throw new IOException( \"Missing connection configuration\" );\n    }\n\n    VariableSpace varSpace = getSpace();\n    if ( varSpace == null ) {\n      throw new IOException( \"Failed to initialize connection variables\" );\n    }\n\n    String connectionName = details.getName();\n\n    // Used by KettleVFSImpl#buildFsOptions -> VFSHelper#getOpts(...).\n    varSpace.setVariable( CONNECTION, connectionName );\n\n    details.setSpace( varSpace );\n\n    return varSpace;\n  }\n\n  @NonNull\n  protected VariableSpace getSpace() throws IOException {\n    VariableSpace varSpace = (VariableSpace) getConfigBuilder().getVariableSpace( getFileSystemOptions() );\n    return varSpace != null ? varSpace : Variables.getADefaultVariableSpace();\n  }\n","sourceCodeStart":187,"sourceCodeEnd":223,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/core/src/main/java/org/pentaho/di/connections/vfs/provider/ConnectionFileSystem.java#L187-L223","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Call KettleEnvironment.init() (which initializes the variable space) before resolving pvfs files","Ensure the ConnectionFileSystem is constructed with a valid variable space supplier","In tests, initialize a Variables/KettleEnvironment instance before creating the filesystem","Check for shutdown code that nulls the space before VFS usage completes"],"exampleFix":"// before\nConnectionFileSystem fs = new ConnectionFileSystem(...); // no env init\n// after\nKettleEnvironment.init();\nConnectionFileSystem fs = new ConnectionFileSystem(...);","handlingStrategy":"try-catch","validationCode":"if (KettleEnvironment.isInitialized() == false) KettleEnvironment.init(); // ensure variable space exists","typeGuard":null,"tryCatchPattern":"try { fo = fs.resolveFile(url); } catch (IOException e) { if (\"Failed to initialize connection variables\".equals(e.getMessage())) { KettleEnvironment.init(); retry(); } }","preventionTips":["Call KettleEnvironment.init() in embedded/headless setups","Initialize variable spaces in test setups before creating filesystems","Verify getSpace() supplier is wired when constructing the filesystem"],"tags":["vfs","variables","initialization","kettle-environment"],"backgroundTag":"missing-env-var","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"}