{"record":{"id":"b827a373a80f813d","repo":"pentaho/pentaho-kettle","slug":"connectionfilesystem-expectedconnectionnotfound","errorCode":"ConnectionFileSystem.ExpectedConnectionNotFound","errorMessage":"ConnectionFileSystem.ExpectedConnectionNotFound","messagePattern":"ConnectionFileSystem\\.ExpectedConnectionNotFound","errorType":"exception","errorClass":"KettleVFSFileSystemException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/pentaho/di/connections/vfs/provider/ConnectionFileSystem.java","lineNumber":191,"sourceCode":"\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 {\n      return manager.getExistingDetails( connectionName );\n    } catch ( KettleException e ) {\n      throw new KettleVFSFileSystemException( \"ConnectionFileSystem.ExpectedConnectionNotFound\", connectionName, e );\n    }\n  }\n\n  @NonNull\n  private VariableSpace initializeVariableSpace( @NonNull VFSConnectionDetails details )\n    throws IOException {\n\n    if ( details == null || details.getName() == null ) {\n      throw new IOException( \"Missing connection configuration\" );\n    }\n\n    VariableSpace varSpace = getSpace();\n    if ( varSpace == null ) {\n      throw new IOException( \"Failed to initialize connection variables\" );\n    }\n\n    String connectionName = details.getName();\n","sourceCodeStart":173,"sourceCodeEnd":209,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/core/src/main/java/org/pentaho/di/connections/vfs/provider/ConnectionFileSystem.java#L173-L209","documentation":"getExistingConnectionDetails calls manager.getExistingDetails(connectionName); a KettleException there is wrapped as ExpectedConnectionNotFound with the connection name. It means the named connection does not exist (or cannot be retrieved) in the ConnectionManager at the time of the pvfs:// resolution.","triggerScenarios":"Resolving or building a pvfs file name for a connection name that is not registered in the ConnectionManager — e.g. the connection was deleted, renamed, or never created in the current environment/repository.","commonSituations":"Hard-coded pvfs:// URLs referencing a connection that doesn't exist in the target environment; moving jobs between environments where connections are defined differently; connection deleted by another user/session.","solutions":["Verify the connection name in the URL matches an existing connection in the connection manager","Create the missing connection or correct the name in the pvfs:// path","Check you are connected to the right repository/environment where the connection is defined","Wrap the cause KettleException to distinguish 'not found' from a lookup failure"],"exampleFix":"// before: URL references non-existent connection\nFileObject f = KettleVFS.getFileObject(\"pvfs://prod-conn/data.csv\");\n// after: ensure the connection exists first\nif (connectionManager.getExistingDetails(\"prod-conn\") != null) {\n  FileObject f = KettleVFS.getFileObject(\"pvfs://prod-conn/data.csv\");\n}","handlingStrategy":"validation","validationCode":"try { connectionManager.getExistingDetails(connName); } catch (KettleException e) { /* connection missing — create it or fail fast */ }","typeGuard":"boolean connectionDefined = !manager.getDetails().stream().noneMatch(d -> d.getName().equals(connName));","tryCatchPattern":"try { resolvePvfs(connName); } catch (FileSystemException e) { if (causeCode == ExpectedConnectionNotFound) { createOrSelectConnection(); retry(); } }","preventionTips":["Never hard-code pvfs connection names across environments","List available connections and validate names before use","Manage connections via the connection dialog/environment config"],"tags":["vfs","connection-not-found","configuration"],"backgroundTag":"resource-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"}