pentaho/pentaho-kettle · error · KettleVFSFileSystemException

ConnectionFileSystem.FailedTransformProviderFilename

ConnectionFileSystem.FailedTransformProviderFilename

Error message

ConnectionFileSystem.FailedTransformProviderFilename

What it means

toPvfsFileName delegates to the connection's provider FileNameTransformer; any IOException or KettleException raised during that transformation is wrapped into a KettleVFSFileSystemException with the provider file name and connection name as message arguments. It means the provider could not translate its native path into a pvfs:// path.

Solutions

Check the wrapped cause to see whether the IOException or KettleException came from the transformer or variable init
Confirm the provider file name actually belongs to the named connection (right bucket/prefix)
Verify the connection's configuration (bucket, path prefix, variables) is valid and resolvable
Test the connection in the connection dialog to validate its file-name transformation

Example fix

// before: child built from another connection's path
FileObject child = pvfsFile.resolveFile(otherConnPath);
// after: keep paths within the same connection
FileObject child = pvfsFile.resolveFile("subdir/file.txt");

Defensive patterns

Strategy: validation

Validate before calling

// ensure the path belongs to this connection's provider before transforming
String expectedPrefix = "/" + details.getName();
if (!providerFileName.getPath().startsWith(expectedPrefix)) throw new IllegalArgumentException("path not in connection");

Try / catch

try { pvfs = toPvfsFileName(fn, conn); } catch (FileSystemException e) { /* log fn + connection name from message args, fix path/connection */ }

Prevention

Only build child names from paths owned by the same connection
Validate connection settings (bucket/prefix) resolve without IOException
Test connections in the UI to validate transformers

When it happens

Trigger: childPvfsFileName -> toPvfsFileName where the provider's getFileNameTransformer().toPvfsFileName(...) throws — e.g. the provider path doesn't match the connection's bucket/layout rules, variable initialization (IOException) fails, or the provider's transformation logic raises a KettleException.

Common situations: Path layouts that don't belong to the connection (mixing connections in a path); S3/GCS-style providers rejecting a path outside their bucket; variable space init failing while expanding variables in connection settings.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

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

  @NonNull
  protected ConnectionFileName toPvfsFileName( @NonNull FileName providerFileName, @NonNull String connectionName )
    throws FileSystemException {

    ConnectionManager locConnMgr = this.connectionManager.get();
    if ( locConnMgr == null ) {
      throw new KettleVFSFileSystemException( "ConnectionFileSystem.ConnectionManagerGone" );
    }
    VFSConnectionDetails details = getExistingConnectionDetails( locConnMgr, connectionName );

    try {
      initializeVariableSpace( details );
      return vfsConnectionManagerHelper
        .getExistingProvider( locConnMgr, details )
        .getFileNameTransformer( locConnMgr )
        .toPvfsFileName( providerFileName, details );
    } catch ( IOException | KettleException e ) {
      throw new KettleVFSFileSystemException(
        "ConnectionFileSystem.FailedTransformProviderFilename",
        e,
        providerFileName.toString(),
        details.getName() );
    }
  }

  @Override
  protected void addCapabilities( Collection<Capability> collection ) {
    collection.addAll( ConnectionFileProvider.capabilities );
  }

  @Override
  public FileObject resolveFile( FileName name ) throws FileSystemException {
    try {
      return createFile( (AbstractFileName) name );
    } catch ( Exception e ) {
      throw new FileSystemException( "vfs.provider/resolve-file.error", name, e );

View on GitHub (pinned to f3058517a1)