{"record":{"id":"33411c024539394e","repo":"apache/hadoop","slug":"invalid-or-missing-xferport-in-server-response","errorCode":null,"errorMessage":"Invalid or missing 'xferPort' in server response.","messagePattern":"Invalid or missing 'xferPort' in server response\\.","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/web/JsonUtilClient.java","lineNumber":345,"sourceCode":"      if (name != null) {\n        int colonIdx = name.indexOf(':');\n        if (colonIdx > 0) {\n          ipAddr = name.substring(0, colonIdx);\n          xferPort = Integer.parseInt(name.substring(colonIdx +1));\n        } else {\n          throw new IOException(\n              \"Invalid value in server response: name=[\" + name + \"]\");\n        }\n      } else {\n        throw new IOException(\n            \"Missing both 'ipAddr' and 'name' in server response.\");\n      }\n      // ipAddr is non-null & non-empty string at this point.\n    }\n\n    // Check the validity of xferPort.\n    if (xferPort == -1) {\n      throw new IOException(\n          \"Invalid or missing 'xferPort' in server response.\");\n    }\n\n    // TODO: Fix storageID\n    return new DatanodeInfoBuilder().setIpAddr(ipAddr)\n        .setHostName((String) m.get(\"hostName\"))\n        .setDatanodeUuid((String) m.get(\"storageID\")).setXferPort(xferPort)\n        .setInfoPort(((Number) m.get(\"infoPort\")).intValue())\n        .setInfoSecurePort(getInt(m, \"infoSecurePort\", 0))\n        .setIpcPort(((Number) m.get(\"ipcPort\")).intValue())\n        .setCapacity(getLong(m, \"capacity\", 0L))\n        .setDfsUsed(getLong(m, \"dfsUsed\", 0L))\n        .setRemaining(getLong(m, \"remaining\", 0L))\n        .setBlockPoolUsed(getLong(m, \"blockPoolUsed\", 0L))\n        .setCacheCapacity(getLong(m, \"cacheCapacity\", 0L))\n        .setCacheUsed(getLong(m, \"cacheUsed\", 0L))\n        .setLastUpdate(getLong(m, \"lastUpdate\", 0L))\n        .setLastUpdateMonotonic(getLong(m, \"lastUpdateMonotonic\", 0L))","sourceCodeStart":327,"sourceCodeEnd":363,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/web/JsonUtilClient.java#L327-L363","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure every datanode object emitted by the NameNode or gateway has a numeric xferPort, typically 9866 for DFS data transfer in Hadoop 3.","Bypass or fix JSON-rewriting proxies so the original NameNode datanode fields pass through.","Match client and server Hadoop versions so both use the same WebHDFS datanode schema.","If a custom address translation layer is required, make it emit complete ipAddr, xferPort, infoPort, and ipcPort fields."],"exampleFix":"// before: datanode JSON is {\"ipAddr\": \"10.0.0.5\"}\nBlockLocation[] locations = fs.getFileBlockLocations(path, 0, len);\n\n// after: datanode JSON is {\"ipAddr\": \"10.0.0.5\", \"xferPort\": 9866}\nBlockLocation[] locations = fs.getFileBlockLocations(path, 0, len);","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  return fs.open(path);\n} catch (IOException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"'xferPort'\")) {\n    throw new IllegalStateException(\"WebHDFS response omitted a usable datanode xferPort\", e);\n  }\n  throw e;\n}","preventionTips":["Verify gateways forward every datanode field, especially ipAddr, xferPort, infoPort, and ipcPort.","Use the same Hadoop major/minor version on client and server in mixed deployments.","Alert on schema-validation errors from WebHDFS because they indicate a broken intermediary, not a bad path."],"tags":["java","hadoop","webhdfs","json","datanode","port"],"backgroundTag":"malformed-server-response","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}