apache/hadoop · error · IOException

Invalid host specified

Error message

Invalid host specified

What it means

FTPFileSystem.initialize resolves the FTP host from the URI authority first, then falls back to the fs.ftp.host configuration key. If both are absent there is nothing to connect to, so FileSystem.get()/initialize fails immediately with this IOException.

Source

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

  /**
   * Get the default port for this FTPFileSystem.
   *
   * @return the default port
   */
  @Override
  protected int getDefaultPort() {
    return FTP.DEFAULT_PORT;
  }

  @Override
  public void initialize(URI uri, Configuration conf) throws IOException { // get
    super.initialize(uri, conf);
    // get host information from uri (overrides info in conf)
    String host = uri.getHost();
    host = (host == null) ? conf.get(FS_FTP_HOST, null) : host;
    if (host == null) {
      throw new IOException("Invalid host specified");
    }
    conf.set(FS_FTP_HOST, host);

    // get port information from uri, (overrides info in conf)
    int port = uri.getPort();
    if(port == -1){
      port = conf.getInt(FS_FTP_HOST_PORT, FTP.DEFAULT_PORT);
    }
    conf.setInt(FS_FTP_HOST_PORT, port);

    // get user/password information from URI (overrides info in conf)
    String userAndPassword = uri.getUserInfo();
    if (userAndPassword == null) {
      userAndPassword = (conf.get(FS_FTP_USER_PREFIX + host, null) + ":" + conf
          .get(FS_FTP_PASSWORD_PREFIX + host, null));
    }
    String[] userPasswdInfo = userAndPassword.split(":");
    Preconditions.checkState(userPasswdInfo.length > 1,

View on GitHub (pinned to 2add963021)

Solutions

1. Put the host in the URI: ftp://ftp.example.com:21/path (optionally ftp://user:pass@ftp.example.com/path)
2. Or set conf.set("fs.ftp.host", "ftp.example.com") (plus optional fs.ftp.host.port, default 21) before FileSystem.get
3. When building FTP URIs dynamically, assert uri.getHost() != null before use

Example fix

// before
Configuration conf = new Configuration();
FileSystem fs = new Path("ftp:///data/file").getFileSystem(conf);
// IOException: Invalid host specified

// after
Configuration conf = new Configuration();
conf.set("fs.ftp.host", "ftp.example.com");
conf.setInt("fs.ftp.host.port", 21);
FileSystem fs = new Path("ftp:///data/file").getFileSystem(conf);

URI u = URI.create("ftp://" + host + ":" + port + path);
if (u.getHost() == null) {
  throw new IllegalArgumentException("FTP URI has no host: " + u);
}
// or pre-seed config: conf.set("fs.ftp.host", host);

When it happens

Trigger: Using a URI whose authority has no host, e.g. new Path("ftp:///data/file").getFileSystem(conf), or fs.defaultFS=ftp:/// , with no fs.ftp.host entry in the configuration; also ftp://:21/path where the authority parses to a null host.

Common situations: Job XML missing the fs.ftp.host property (typo or dropped during refactor); switching from absolute ftp://host/path URIs to relative paths; tool config built programmatically that never sets the key.

Related errors

• Bad configuration of hadoop.security.key.provider.path at ${
• Uri without authority: {uri}
• Wrong FS: {path}, expected: {this.getUri()}
• No scheme in default FS: ${uri}
• Failed to get home directory

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