apache/hadoop · error · FTPException

Failed to get home directory

Error message

Failed to get home directory

What it means

getHomeDirectory() opens a fresh FTP connection, issues PWD to learn the login directory, and returns it as a Path. Any IOException during connect, login, or PWD is wrapped as FTPException("Failed to get home directory") with the cause preserved. Because FTPFileSystem keeps no state, getWorkingDirectory() delegates here too, so this error can surface from many entry points.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/ftp/FTPFileSystem.java:721

    boolean renamed = client.rename(from, to);
    return renamed;
  }

  @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 {
      try {
        disconnect(client);
      } catch (IOException ioe) {
        throw new FTPException("Failed to disconnect", ioe);
      }
    }
  }

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

View on GitHub (pinned to 2add963021)

Solutions

1. Read exception.getCause(): UnknownHostException vs ConnectException vs login failure points to DNS vs network vs credentials
2. Test the exact URI and credentials with an external FTP client from the same host
3. Set fs.ftp.user.<host>, fs.ftp.password.<host> (or fs.ftp.keypair.encrypted) in the Configuration
4. Open control port 21 and the server's passive data port range in every firewall on the path
5. If the server requires FTPS/TLS, align the endpoint and credential setup, then retest

Example fix

// before
conf.set("fs.defaultFS", "ftp://ftp.example.com/");  // no credentials -> FTPException

// after
conf.set("fs.defaultFS", "ftp://ftp.example.com/");
conf.set("fs.ftp.user.ftp.example.com", "uploader");
conf.set("fs.ftp.password.ftp.example.com", "******");  // or fs.ftp.keypair.encrypted

// cheap probe before relying on the filesystem
try {
  fs.exists(new Path("/"));
} catch (IOException e) {
  throw new RuntimeException("FTP endpoint unusable; check host/port/credentials", e);
}

catch FTPException("Failed to get home directory"), switch on getCause(): UnknownHostException -> fix host; ConnectException -> fix port/firewall; login failure -> fix fs.ftp.user/password config; then rebuild the FileSystem.

When it happens

Trigger: connect() failing — unknown host, wrong port, connection refused, failed login — or printWorkingDirectory() failing after login because the server rejected PWD.

Common situations: Misconfigured fs.defaultFS (wrong scheme, missing port); credentials not set via fs.ftp.user.<host>/fs.ftp.password.<host> or keyfile fs.ftp.keypair.encrypted; firewall blocking control port 21 or the passive data port range; server requiring FTPS while the client is set up for plain FTP.

Related errors

• Client not connected
• No more entry in " + f
• f + " is a directory"
• f + " already exists"
• Missing keyfile property ('%s') for authentication type '%s'

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/6bc035ab73b30914. Report an issue: GitHub.