pentaho/pentaho-kettle · error · IOException

Missing connection configuration

Error message

Missing connection configuration

What it means

initializeVariableSpace validates that the resolved VFSConnectionDetails and its name are non-null before initializing a variable space; otherwise it throws a plain IOException 'Missing connection configuration'. The connection metadata is required to seed variables used by provider file options.

Solutions

1. Open the connection definition and set a valid non-empty name
2. Re-save/recreate the connection to repair corrupted metadata
3. Validate connection details (name present) before resolving pvfs files
4. Inspect the saved repository metadata for the connection object

Example fix

// before: connection saved without a name
VFSConnectionDetails d = new S3VFSConnectionDetails(); // name never set
// after
d.setName("my-s3");
connectionManager.addDetails(d);

boolean valid = details != null && details.getName() != null && !details.getName().isEmpty();

boolean hasName = d instanceof VFSConnectionDetails v && v.getName() != null;

try { fo = fs.resolveFile(url); } catch (IOException e) { if ("Missing connection configuration".equals(e.getMessage())) { /* repair connection metadata */ } }

When it happens

Trigger: createFile or toPvfsFileName path resolves connection details to null (or a details object with a null name) and then calls initializeVariableSpace. Note the null check is defensive — getExistingConnectionDetails normally throws earlier if lookup fails.

Common situations: A connection registered with an empty/unset name; corrupted saved connection metadata; defensive guard hit after a partially-initialized connection object.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• GPG.ErrorCheckingGPGFile
• Illegal move target
• Unable to obtain a IUnifiedRepository instance
• Unexpected null VFS filename.
• A connection of type PALO is expected

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

Appendix: source

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

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

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

    details.setSpace( varSpace );

    return varSpace;
  }

  @NonNull

View on GitHub (pinned to f3058517a1)