pentaho/pentaho-kettle · error · IOException

CustomVfsSettingsParser.Log.FailedToLoad

CustomVfsSettingsParser.Log.FailedToLoad

Error message

CustomVfsSettingsParser.Log.FailedToLoad

What it means

KettleFileSystemConfigBuilder.getConfigBuilder() throws this IOException when loading a custom VFS config builder class (named via CustomVfsSettings) fails — the class cannot be found, instantiated, or its getInstance() invocation fails. The message key 'CustomVfsSettingsParser.Log.FailedToLoad' is resolved from BaseMessages at runtime.

Solutions

1. Check the custom VFS settings file for the correct config-builder class name
2. Ensure the plugin JAR containing the builder is on the classpath (lib/plugins directory)
3. Verify the class implements IKettleFileSystemConfigBuilder and has a public no-arg constructor or static getInstance()
4. Temporarily remove the custom setting to fall back to the default builder and confirm the custom class is the culprit
5. Check the plugin's dependency versions match the Kettle/PDI version

String cls = settings.getConfigBuilderClass();
if ( cls != null ) {
  try {
    Class.forName( cls );
  } catch ( ClassNotFoundException e ) {
    System.out.println( "Custom builder missing from classpath: " + cls );
  }
}

When it happens

Trigger: A VFS scheme has a custom config builder configured, and Class.forName/newInstance/invoke of that builder throws during getConfigBuilder().

Common situations: Typo or wrong FQCN in custom VFS settings file, plugin JAR missing from classpath, builder class lacking a no-arg constructor or getInstance(), class cast failures after plugin refactor.

Related errors

• ConnectionFileSystem.ExpectedConnectionNotFound
• 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/2b1ddeba5295bf81. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/core/vfs/configuration/KettleFileSystemConfigBuilderFactory.java:66

    IKettleFileSystemConfigBuilder result = null;

    // Attempt to load the Config Builder from a variable: vfs.config.parser = class
    String parserClass = varSpace.getVariable( "vfs." + scheme + ".config.parser" );

    if ( parserClass != null ) {
      try {
        Class<?> configBuilderClass =
          KettleFileSystemConfigBuilderFactory.class.getClassLoader().loadClass( parserClass );
        Method mGetInstance = configBuilderClass.getMethod( "getInstance" );
        if ( ( mGetInstance != null )
          && ( IKettleFileSystemConfigBuilder.class.isAssignableFrom( mGetInstance.getReturnType() ) ) ) {
          result = (IKettleFileSystemConfigBuilder) mGetInstance.invoke( null );
        } else {
          result = (IKettleFileSystemConfigBuilder) configBuilderClass.newInstance();
        }
      } catch ( Exception e ) {
        // Failed to load custom parser. Throw exception.
        throw new IOException( BaseMessages.getString( PKG, "CustomVfsSettingsParser.Log.FailedToLoad" ) );
      }
    } else {
      // No custom parser requested, load default
      if ( scheme.equalsIgnoreCase( "sftp" ) ) {
        result = KettleSftpFileSystemConfigBuilder.getInstance();
      } else {
        result = KettleGenericFileSystemConfigBuilder.getInstance();
      }
    }

    return result;
  }

}

View on GitHub (pinned to f3058517a1)