pentaho/pentaho-kettle · error · FileSystemException

vfs.provider/resolve-file.error

vfs.provider/resolve-file.error

Error message

vfs.provider/resolve-file.error

What it means

This is ConnectionFileSystem's public resolveFile(FileName) wrapper: any Exception escaping createFile (including the KettleVFSFileSystemException guards above) is rethrown as a standard VFS FileSystemException with code 'vfs.provider/resolve-file.error'. It is a generic VFS-level resolution failure for pvfs:// names.

Solutions

1. Unwrap the cause chain — the specific KettleVFSFileSystemException code is the real reason
2. Verify the pvfs URL and referenced connection exist before resolving
3. Confirm the ConnectionManager is alive and the filesystem is initialized
4. Catch FileSystemException and inspect getCause() to branch on the specific error code

Example fix

// before
FileObject f = fs.resolveFile(name); // opaque failure
// after
try {
  FileObject f = fs.resolveFile(name);
} catch (FileSystemException e) {
  Throwable root = e.getCause();
  if (root instanceof KettleVFSFileSystemException) { /* handle specific code */ }
  throw e;
}

boolean connExists = connectionManager.getExistingDetails(connName) != null; // check before resolveFile

try { fo = fs.resolveFile(name); } catch (FileSystemException e) { Throwable c = e.getCause(); while (c != null && !(c instanceof KettleVFSFileSystemException)) c = c.getCause(); }

When it happens

Trigger: Calling resolveFile on a pvfs name when createFile throws — dead ConnectionManager, unknown connection, transformation failure, or any other exception in file object construction.

Common situations: Generic catch-all seen in logs when pvfs resolution fails for any reason; developers often see this code instead of the more specific cause nested inside.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• AbstractFileErrorHandler.Exception.CouldNotCreateFileErrorHandlerForFile
• Append file in repository is not possible
• [ + ArgList[0] + ] is not a file!
• [ + ArgList[0] + ] is not a folder!
• Argument 'name' is not the PVFS root.

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

Appendix: source

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

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

  // region Helpers
  @NonNull
  protected Bowl getBowl() {
    return KettleGenericFileSystemConfigBuilder.getInstance().getBowl( getFileSystemOptions() );
  }

  @NonNull
  protected IKettleVFS getKettleVFS() {
    return KettleVFS.getInstance( getBowl() );
  }

  @NonNull
  private VFSConnectionDetails getExistingConnectionDetails( @NonNull ConnectionManager manager, @NonNull String connectionName )
    throws KettleVFSFileSystemException {
    try {

View on GitHub (pinned to f3058517a1)