apache/seatunnel · error · FTPException

Failed to get home directory

Error message

Failed to get home directory

What it means

getHomeDirectory() connects to the FTP server and builds a Path from client.printWorkingDirectory(). Any IOException during connect() or printWorkingDirectory() is wrapped as FTPException 'Failed to get home directory'; the client is disconnected in finally.

Solutions

1. Check the wrapped cause (getCause()) for the underlying connect/login failure
2. Validate ftp host, port, user, password in the connector config; test with ftp/lftp manually
3. Verify network reachability: telnet/nc to the FTP port; check firewall/NAT and enable passive mode if needed
4. Confirm the FTP service is running and accepting connections (server logs)

Example fix

// before
Path home = ftpFileSystem.getHomeDirectory(); // throws FTPException on bad config
// after
try {
    Path home = ftpFileSystem.getHomeDirectory();
} catch (FTPException e) {
    log.error("FTP home lookup failed; check host/port/credentials. Cause: {}", e.getCause());
    throw e;
}

// shell: verify FTP reachability before job
nc -zv $FTP_HOST $FTP_PORT || echo "FTP unreachable"

try {
    Path home = ftpFileSystem.getHomeDirectory();
} catch (FTPException e) {
    logger.error("FTP home lookup failed; check host/port/credentials. Cause: {}", e.getCause());
    throw e;
}

When it happens

Trigger: getHomeDirectory() invoked and connect() fails (bad host/port, auth rejected, network unreachable) or printWorkingDirectory() throws while negotiating with the FTP server.

Common situations: FTP host/port/credentials wrong in config; FTP server down or unreachable (firewall, DNS); passive-mode port blocked so the control connection opens but data-related commands fail; server rejects the user at login.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• Client not connected
• File check failed
• Server response
• BUILD_CLIENT_FAILED
• Can't make directory for path

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/88e208a70311afbb. Report an issue: GitHub.

Appendix: source

Thrown at seatunnel-connectors-v2/connector-file/connector-file-ftp/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/ftp/system/SeaTunnelFTPFileSystem.java:867

        String to = absoluteDst.toUri().getPath();
        return client.rename(from, to);
    }

    @Override
    public Path getWorkingDirectory() {
        // Return home directory always since we do not maintain state.
        return getHomeDirectory();
    }

    @Override
    public Path getHomeDirectory() {
        FTPClient client = null;
        try {
            client = connect();
            Path homeDir = new Path(client.printWorkingDirectory());
            return homeDir;
        } catch (IOException ioe) {
            throw new FTPException("Failed to get home directory", ioe);
        } finally {
            disconnect(client);
        }
    }

    @Override
    public void setWorkingDirectory(Path newDir) {
        // we do not maintain the working directory state
    }
}

View on GitHub (pinned to cf67b549a7)