pentaho/pentaho-kettle · error · IOException

FileSystemConfigBuilder could not parse parameter:

Error message

FileSystemConfigBuilder could not parse parameter: 

What it means

KettleVFSImpl.buildFsOptions maps Kettle variables like vfs.xxx.param=value into commons-vfs FileSystemOptions. For each variable it asks the config builder to extract a parameter name; if the variable's prefix (after scheme extraction) doesn't map to a known parameter, param is null and an IOException "FileSystemConfigBuilder could not parse parameter: <var>" is thrown. This means a VFS.* variable is set that no scheme's config builder recognizes.

Solutions

1. Read the variable name in the message and correct the parameter name to the one the scheme's FileSystemConfigBuilder expects (e.g. vfs.sftp.identyKey, vfs.sftp.StrictHostKeyChecking).
2. Remove the stray vfs.* variable if it isn't needed.
3. Check the PDI version's supported VFS parameter names in the KettleGenericFileSystemConfigBuilder and scheme-specific builders.
4. Ensure the variable's scheme matches the scheme being configured (or use no scheme prefix for generic ones).

Example fix

// before (kettle.properties)
vfs.sftp.identykey=/home/user/.ssh/id_rsa
// after
vfs.sftp.identyKey=/home/user/.ssh/id_rsa

// only pass variables the config builder understands
if (var.startsWith("vfs.") && !KNOWN_VFS_PARAMS.contains(var)) {
  log.warn("Ignoring unknown VFS variable: " + var);
}

try {
  opts = KettleVFS.getInstance().getFileSystemOptions(scheme, file, space);
} catch (IOException e) {
  if (e.getMessage().startsWith("FileSystemConfigBuilder could not parse parameter")) {
    throw new KettleException("Fix or remove the vfs.* variable named in the message", e);
  }
  throw e;
}

When it happens

Trigger: Setting a variable like vfs.sftp.UnknownParam=xyz (or a misspelled one such as vfs.sftp.identykey instead of identyKey) in kettle.properties, a transformation, or the environment, then calling getFileSystemOptions for that scheme.

Common situations: Upgrading Kettle/PDI where parameter names changed; copying variables from documentation for a different scheme (e.g. using http params with sftp); typos in variable names; passing arbitrary variables with the vfs.* prefix expecting them to be ignored.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• ChangeFileEncoding.Exception.TargetEncodingEmpty
• ConnectionFileSystem.ExpectedConnectionNotFound
• Could not get the groups of the current user (error code: )
• Could not get user name on remote host (error code: )
• CustomVfsSettingsParser.Log.FailedToLoad

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

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/core/vfs/KettleVFSImpl.java:213

      String[] varList = varSpace.listVariables();

      for ( String var : varList ) {
        if ( var.equalsIgnoreCase( CONNECTION ) && varSpace.getVariable( var ) != null ) {
          FileSystemOptions fileSystemOptions = VFSHelper.getOpts( bowl, vfsFilename, varSpace.getVariable( var ),
                                                                   varSpace );
          if ( fileSystemOptions != null ) {
            return fileSystemOptions;
          }
        }
        if ( var.startsWith( "vfs." ) ) {
          String param = configBuilder.parseParameterName( var, scheme );
          String varScheme = KettleGenericFileSystemConfigBuilder.extractScheme( var );
          if ( param != null ) {
            if ( varScheme == null || varScheme.equals( "sftp" ) || varScheme.equals( scheme ) ) {
              configBuilder.setParameter( fsOptions, param, varSpace.getVariable( var ), var, vfsFilename );
            }
          } else {
            throw new IOException( "FileSystemConfigBuilder could not parse parameter: " + var );
          }
        }
      }
      if ( scheme.equals( "pvfs" ) ) {
        configBuilder.setParameter( fsOptions, "VariableSpace", varSpace, vfsFilename );
      }
    } catch ( KettleException ex ) {
      // keep backward compatible API in KettleVFS
      throw new IOException( ex );
    }
    return fsOptions;
  }

  @Override
  public String getFriendlyURI( String filename ) {
    return getFriendlyURI( filename, defaultVariableSpace.get() );
  }

View on GitHub (pinned to f3058517a1)