apache/hadoop · error · IOException

Invalid or missing 'xferPort' in server response.

Error message

Invalid or missing 'xferPort' in server response.

What it means

JsonUtilClient.toDatanodeInfo initializes xferPort to -1 and then validates it after resolving ipAddr or legacy name. This IOException means ipAddr was available, but the response did not contain a usable xferPort. Since xferPort is the port used for block transfers, the client cannot safely continue with a default.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/web/JsonUtilClient.java:345

      if (name != null) {
        int colonIdx = name.indexOf(':');
        if (colonIdx > 0) {
          ipAddr = name.substring(0, colonIdx);
          xferPort = Integer.parseInt(name.substring(colonIdx +1));
        } else {
          throw new IOException(
              "Invalid value in server response: name=[" + name + "]");
        }
      } else {
        throw new IOException(
            "Missing both 'ipAddr' and 'name' in server response.");
      }
      // ipAddr is non-null & non-empty string at this point.
    }

    // Check the validity of xferPort.
    if (xferPort == -1) {
      throw new IOException(
          "Invalid or missing 'xferPort' in server response.");
    }

    // TODO: Fix storageID
    return new DatanodeInfoBuilder().setIpAddr(ipAddr)
        .setHostName((String) m.get("hostName"))
        .setDatanodeUuid((String) m.get("storageID")).setXferPort(xferPort)
        .setInfoPort(((Number) m.get("infoPort")).intValue())
        .setInfoSecurePort(getInt(m, "infoSecurePort", 0))
        .setIpcPort(((Number) m.get("ipcPort")).intValue())
        .setCapacity(getLong(m, "capacity", 0L))
        .setDfsUsed(getLong(m, "dfsUsed", 0L))
        .setRemaining(getLong(m, "remaining", 0L))
        .setBlockPoolUsed(getLong(m, "blockPoolUsed", 0L))
        .setCacheCapacity(getLong(m, "cacheCapacity", 0L))
        .setCacheUsed(getLong(m, "cacheUsed", 0L))
        .setLastUpdate(getLong(m, "lastUpdate", 0L))
        .setLastUpdateMonotonic(getLong(m, "lastUpdateMonotonic", 0L))

View on GitHub (pinned to 2add963021)

Solutions

1. Ensure every datanode object emitted by the NameNode or gateway has a numeric xferPort, typically 9866 for DFS data transfer in Hadoop 3.
2. Bypass or fix JSON-rewriting proxies so the original NameNode datanode fields pass through.
3. Match client and server Hadoop versions so both use the same WebHDFS datanode schema.
4. If a custom address translation layer is required, make it emit complete ipAddr, xferPort, infoPort, and ipcPort fields.

Example fix

// before: datanode JSON is {"ipAddr": "10.0.0.5"}
BlockLocation[] locations = fs.getFileBlockLocations(path, 0, len);

// after: datanode JSON is {"ipAddr": "10.0.0.5", "xferPort": 9866}
BlockLocation[] locations = fs.getFileBlockLocations(path, 0, len);

try {
  return fs.open(path);
} catch (IOException e) {
  if (e.getMessage() != null && e.getMessage().contains("'xferPort'")) {
    throw new IllegalStateException("WebHDFS response omitted a usable datanode xferPort", e);
  }
  throw e;
}

When it happens

Trigger: A datanode object contains ipAddr but omits xferPort, or explicitly sends xferPort = -1. The legacy name path that would derive the port was not used because ipAddr was present. Block-location and open responses with such an object trigger the error during decoding.

Common situations: A custom WebHDFS proxy copies ipAddr but drops xferPort; a server or client from an incompatible Hadoop generation; a hand-written mock response; a gateway that rewrites DataNode fields for containerized networking.

Related errors

• Invalid value in server response: name=[${name}]
• Missing both 'ipAddr' and 'name' in server response.
• The ${useErrorStream ? "error" : "input"} stream is null.
• Content-Type "${contentType}" is incompatible with "applicat
• Unexpected HTTP response: code=${code} != ${op.getExpectedHt

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