{"record":{"id":"2badb79341cc23cd","repo":"pentaho/pentaho-kettle","slug":"vfs-provider-sftp-connect-error","errorCode":"vfs.provider.sftp/connect.error","errorMessage":"vfs.provider.sftp/connect.error","messagePattern":"vfs\\.provider\\.sftp/connect\\.error","errorType":"error_code","errorClass":"FileSystemException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/pentaho/di/core/vfs/SftpFileSystemWindowsProvider.java","lineNumber":78,"sourceCode":"   * Creates a new Session.  Note that this method is borrowed from the parent class and should mirror it if the\n   * commons-vfs2 library is updated.\n   *\n   * @return A Session, never null.\n   */\n  static Session createSession( final GenericFileName rootName, final FileSystemOptions fileSystemOptions )\n    throws FileSystemException {\n    UserAuthenticationData authData = null;\n    try {\n      authData = UserAuthenticatorUtils.authenticate( fileSystemOptions, AUTHENTICATOR_TYPES );\n\n      return SftpClientFactory.createConnection( rootName.getHostName(), rootName.getPort(),\n        UserAuthenticatorUtils.getData( authData, UserAuthenticationData.USERNAME,\n          UserAuthenticatorUtils.toChar( rootName.getUserName() ) ),\n        UserAuthenticatorUtils.getData( authData, UserAuthenticationData.PASSWORD,\n          UserAuthenticatorUtils.toChar( rootName.getPassword() ) ),\n        fileSystemOptions );\n    } catch ( final Exception e ) {\n      throw new FileSystemException( \"vfs.provider.sftp/connect.error\", rootName, e );\n    } finally {\n      UserAuthenticatorUtils.cleanup( authData );\n    }\n  }\n\n  @Override\n  protected FileSystem doCreateFileSystem( FileName name, FileSystemOptions fileSystemOptions )\n    throws FileSystemException {\n    return new SftpFileSystemWindows(\n      (GenericFileName) name, createSession( (GenericFileName) name, fileSystemOptions ), fileSystemOptions );\n  }\n\n}\n","sourceCodeStart":60,"sourceCodeEnd":92,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/core/src/main/java/org/pentaho/di/core/vfs/SftpFileSystemWindowsProvider.java#L60-L92","documentation":"Thrown by SftpFileSystemWindowsProvider.createSession() when establishing the JSch SFTP session (with username/password from the authenticator) throws for any reason; it is wrapped in a FileSystemException keyed to 'vfs.provider.sftp/connect.error'.","triggerScenarios":"doCreateFileSystem() connecting to an SFTP server: unreachable host/port, wrong credentials, unknown host key, SSH handshake failure, JSch library errors.","commonSituations":"Wrong hostname or port in vfs.sftp.* URI, expired or changed password, host key not in known_hosts (StrictHostKeyChecking), firewall blocking port 22, server temporarily down.","solutions":["Test connectivity: ping/ssh to host:port; confirm the server is listening and reachable","Verify username/password in the VFS URI or UserAuthenticator","Handle host-key acceptance (set trusted host key or adjust StrictHostKeyChecking in fileSystemOptions)","Inspect the wrapped cause 'e' for the underlying JSch error (timeout, auth fail, etc.)","Retry on transient network errors with backoff"],"exampleFix":"// before\nFileSystemManager fsManager = VFS.getManager();\nFileObject fo = fsManager.resolveFile( \"sftp://badhost/data\" );\n// after\ntry {\n  FileObject fo = fsManager.resolveFile( \"sftp://badhost/data\" );\n} catch ( FileSystemException e ) {\n  if ( e.getMessage().contains( \"connect.error\" ) ) {\n    throw new KettleException( \"Cannot connect to SFTP server; check host, credentials and network\", e );\n  }\n  throw e;\n}","handlingStrategy":"try-catch","validationCode":"// Pre-flight: check TCP reachability\ntry ( Socket s = new Socket( host, 22 ) ) {\n  System.out.println( \"SFTP port reachable\" );\n} catch ( IOException e ) {\n  System.out.println( \"Host/port unreachable: \" + e.getMessage() );\n}","typeGuard":null,"tryCatchPattern":"try {\n  FileObject fo = fsManager.resolveFile( \"sftp://user@host/path\" );\n} catch ( FileSystemException e ) {\n  // e.getMessage() == \"vfs.provider.sftp/connect.error\"; inspect e.getCause() (JSch) for auth vs network\n  if ( e.getCause() instanceof JSchException ) {\n    JSchException je = (JSchException) e.getCause();\n    // handle auth failure vs timeout vs host key\n  }\n}","preventionTips":["Validate hostname, port and credentials in a connection test step first","Pre-install trusted host keys or configure StrictHostKeyChecking explicitly","Check firewall/VPN allows outbound SSH","Use key-based auth to avoid password expiry issues"],"tags":["sftp","vfs","connection","authentication"],"backgroundTag":"connection-refused","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"}