{"record":{"id":"f5872347585c5337","repo":"pentaho/pentaho-kettle","slug":"vfs-provider-resolve-file-error","errorCode":"vfs.provider/resolve-file.error","errorMessage":"vfs.provider/resolve-file.error","messagePattern":"vfs\\.provider/resolve-file\\.error","errorType":"exception","errorClass":"FileSystemException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/pentaho/di/connections/vfs/provider/ConnectionFileSystem.java","lineNumber":170,"sourceCode":"      throw new KettleVFSFileSystemException(\n        \"ConnectionFileSystem.FailedTransformProviderFilename\",\n        e,\n        providerFileName.toString(),\n        details.getName() );\n    }\n  }\n\n  @Override\n  protected void addCapabilities( Collection<Capability> collection ) {\n    collection.addAll( ConnectionFileProvider.capabilities );\n  }\n\n  @Override\n  public FileObject resolveFile( FileName name ) throws FileSystemException {\n    try {\n      return createFile( (AbstractFileName) name );\n    } catch ( Exception e ) {\n      throw new FileSystemException( \"vfs.provider/resolve-file.error\", name, e );\n    }\n  }\n\n  // region Helpers\n  @NonNull\n  protected Bowl getBowl() {\n    return KettleGenericFileSystemConfigBuilder.getInstance().getBowl( getFileSystemOptions() );\n  }\n\n  @NonNull\n  protected IKettleVFS getKettleVFS() {\n    return KettleVFS.getInstance( getBowl() );\n  }\n\n  @NonNull\n  private VFSConnectionDetails getExistingConnectionDetails( @NonNull ConnectionManager manager, @NonNull String connectionName )\n    throws KettleVFSFileSystemException {\n    try {","sourceCodeStart":152,"sourceCodeEnd":188,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/core/src/main/java/org/pentaho/di/connections/vfs/provider/ConnectionFileSystem.java#L152-L188","documentation":"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.","triggerScenarios":"Calling resolveFile on a pvfs name when createFile throws — dead ConnectionManager, unknown connection, transformation failure, or any other exception in file object construction.","commonSituations":"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.","solutions":["Unwrap the cause chain — the specific KettleVFSFileSystemException code is the real reason","Verify the pvfs URL and referenced connection exist before resolving","Confirm the ConnectionManager is alive and the filesystem is initialized","Catch FileSystemException and inspect getCause() to branch on the specific error code"],"exampleFix":"// before\nFileObject f = fs.resolveFile(name); // opaque failure\n// after\ntry {\n  FileObject f = fs.resolveFile(name);\n} catch (FileSystemException e) {\n  Throwable root = e.getCause();\n  if (root instanceof KettleVFSFileSystemException) { /* handle specific code */ }\n  throw e;\n}","handlingStrategy":"try-catch","validationCode":"boolean connExists = connectionManager.getExistingDetails(connName) != null; // check before resolveFile","typeGuard":null,"tryCatchPattern":"try { fo = fs.resolveFile(name); } catch (FileSystemException e) { Throwable c = e.getCause(); while (c != null && !(c instanceof KettleVFSFileSystemException)) c = c.getCause(); }","preventionTips":["Always unwrap the cause chain to find the specific error code","Pre-validate pvfs URLs and connection existence","Centralize pvfs resolution in one guarded helper"],"tags":["vfs","resolve-file","wrapper"],"backgroundTag":"file-not-found","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}