{"record":{"id":"f30fa74a07550132","repo":"apache/hadoop","slug":"unexpected-data-node-at-an-illegal-network-loca","errorCode":null,"errorMessage":"Unexpected data node {} at an illegal network location","messagePattern":"Unexpected data node (.+?) at an illegal network location","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/net/NetworkTopology.java","lineNumber":151,"sourceCode":"  public void add(Node node) {\n    if (node==null) return;\n    int newDepth = NodeBase.locationToDepth(node.getNetworkLocation()) + 1;\n    netlock.writeLock().lock();\n    try {\n      if( node instanceof InnerNode ) {\n        throw new IllegalArgumentException(\n          \"Not allow to add an inner node: \"+NodeBase.getPath(node));\n      }\n      if ((depthOfAllLeaves != -1) && (depthOfAllLeaves != newDepth)) {\n        LOG.error(\"Error: can't add leaf node {} at depth {} to topology:{}\\n\",\n            NodeBase.getPath(node), newDepth, this);\n        throw new InvalidTopologyException(\"Failed to add \" + NodeBase.getPath(node) +\n            \": You cannot have a rack and a non-rack node at the same \" +\n            \"level of the network topology.\");\n      }\n      Node rack = getNodeForNetworkLocation(node);\n      if (rack != null && !(rack instanceof InnerNode)) {\n        throw new IllegalArgumentException(\"Unexpected data node \" \n                                           + node.toString() \n                                           + \" at an illegal network location\");\n      }\n      if (clusterMap.add(node)) {\n        LOG.info(\"Adding a new node: \"+NodeBase.getPath(node));\n        if (rack == null) {\n          incrementRacks();\n        }\n        interAddNodeWithEmptyRack(node);\n        if (depthOfAllLeaves == -1) {\n          depthOfAllLeaves = node.getLevel();\n        }\n      }\n      LOG.debug(\"NetworkTopology became:\\n{}\", this);\n    } finally {\n      netlock.writeLock().unlock();\n    }\n  }","sourceCodeStart":133,"sourceCodeEnd":169,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/net/NetworkTopology.java#L133-L169","documentation":"During add(), getNodeForNetworkLocation(node) (NetworkTopology.java:193) returns getNode(node.getNetworkLocation()) — the node already registered at the position where the new leaf's rack must sit. That position must be an InnerNode; if a data (leaf) node already occupies it, the topology is self-contradictory and the add is rejected.","triggerScenarios":"A leaf registered with a shallow location makes its full path look like a rack path (e.g. a node named 'r1' registered at root has path /r1); when another node is then mapped to location /r1, getNode('/r1') returns that leaf, not an InnerNode, and the exception fires.","commonSituations":"StaticMapping (net.topology.node.switch.mapping.impl) key-value data where one host's location value equals another host's name; topology scripts returning a bare hostname as a location for some nodes; name/location collisions after re-registering nodes with edited mappings.","solutions":["Run `hdfs dfsadmin -printTopology` and find the data node sitting where a rack should be; correct that host's mapping to a real rack path","Ensure no node's network location equals another node's name or full path — hosts and racks must occupy different levels","Fix the mapping data/script and re-register the affected nodes"],"exampleFix":"// before: mapping collides — host 'dn9' is itself a datanode\ndn1 -> /dn9\n\n// after: racks and host names live on different levels\ndn1 -> /rack1\ndn9 -> /rack1","handlingStrategy":"validation","validationCode":"Node rack = topology.getNode(node.getNetworkLocation());\nif (rack != null && !(rack instanceof InnerNode)) {\n  throw new IllegalStateException(\"Leaf \" + rack.getName()\n      + \" occupies rack position \" + node.getNetworkLocation());\n}\ntopology.add(node);","typeGuard":"static boolean rackPositionIsFreeOrInner(NetworkTopology t, Node candidate) {\n  Node at = t.getNode(candidate.getNetworkLocation());\n  return at == null || at instanceof InnerNode;\n}","tryCatchPattern":"catch (IllegalArgumentException e) {\n  if (e.getMessage().contains(\"illegal network location\")) {\n    // mapping collision: re-check topology and re-register with corrected location\n  }\n}","preventionTips":["Keep host names and rack names in separate namespaces in mapping data","Lint StaticMapping files for values that equal any host name","Print the topology after bulk registration to spot leaves at rack positions"],"tags":["hadoop-common","network-topology","configuration","invalid-topology"],"backgroundTag":"network-topology-location-collision","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}