pentaho/pentaho-kettle · error · FileSystemException

vfs.provider/invalid-scheme

vfs.provider/invalid-scheme

Error message

vfs.provider/invalid-scheme

What it means

extractPvfsScheme parses the scheme off a pvfs URI using UriParser.extractScheme with the parser's supported SCHEMES. If the URI has no scheme, or what precedes '//' is not a supported scheme (e.g. a Windows drive letter like 'c:'), extractScheme returns null and a FileSystemException with message 'vfs.provider/invalid-scheme' is thrown.

Solutions

1. Prefix the URI with the supported scheme: 'pvfs://my-connection/path'.
2. Check the scheme yourself (uri.substring before "://") and reject or convert non-pvfs URIs before calling parseUri.
3. Fix typos in the scheme name to match the parser's SCHEMES list exactly (case as supported).
4. On Windows, ensure drive-letter paths are converted to proper URIs before PVFS parsing.

Example fix

// before
FileName name = parser.parseUri( "my-connection/folder" ); // throws invalid-scheme
// after
String uri = uri.startsWith( "pvfs://" ) ? uri : "pvfs://" + uri;
FileName name = parser.parseUri( uri );

if ( uri == null || !uri.matches( "(?i)^pvfs://.*" ) ) {
  uri = "pvfs://" + uri.replaceFirst( "^[a-zA-Z]:\\\\?", "" );
}

boolean hasSupportedScheme( String uri ) {
  int i = uri.indexOf( ':' );
  return i > 0 && uri.regionMatches( true, 0, "pvfs", 0, i ) && uri.startsWith( "//", i + 1 );
}

try {
  return parser.parseUri( uri );
} catch ( FileSystemException e ) {
  if ( "vfs.provider/invalid-scheme".equals( e.getMessage() ) ) {
    // convert the path to a pvfs URI or report a config error
  }
  throw e;
}

When it happens

Trigger: Calling parser.parseUri with a URI lacking the pvfs scheme — e.g. 'my-connection/folder/file.txt', 'file:///some/path', or a bare Windows path 'C:\data' that looks like a scheme but isn't in SCHEMES.

Common situations: Passing plain filesystem paths to a parser that expects pvfs URIs; users omitting 'pvfs://' in configured file locations; using a related but unsupported scheme name (typo like 'pvfs2://').

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• ConnectionFileNameParser.ConnectionNameEmpty
• ConnectionFileNameParser.ConnectionNameInvalidCharacter
• vfs.provider/missing-double-slashes.error
• AbstractFileErrorHandler.Exception.CouldNotCreateFileErrorHandlerForFile
• Append file in repository is not possible

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

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/connections/vfs/provider/ConnectionFileNameParser.java:281

    // When name is empty, fileType is FOLDER, which is the correct type for either the root or connection folder.
    FileType fileType = UriParser.normalisePath( name );

    // Examples: name = "" | "Folder/Sub Folder/100%25"

    getConnectionFileNameUtils().ensureLeadingSeparator( name );

    // Examples: name = "/" | "/Folder/Sub Folder/100%25"

    String path = name.toString();

    return new ConnectionFileName( connectionName, path, fileType );
  }

  private void extractPvfsScheme( String uri, StringBuilder name ) throws FileSystemException {
    // UriParser.extractScheme initializes `name` with the contents of uri, and only then extracts the scheme.
    // Scheme may not be present, or invalid (e.g. drive letter), in which case null is returned.
    if ( UriParser.extractScheme( SCHEMES, uri, name ) == null ) {
      throw new FileSystemException( "vfs.provider/invalid-scheme" );
    }

    // Extract "//" (based on HostFileNameParser#parseUri(..))
    // These two are not supported as "\".
    if ( name.length() < 2 || name.charAt( 0 ) != SEPARATOR_CHAR || name.charAt( 1 ) != SEPARATOR_CHAR ) {
      throw new FileSystemException( "vfs.provider/missing-double-slashes.error", uri );
    }

    name.delete( 0, 2 );
  }
}

View on GitHub (pinned to f3058517a1)