{"record":{"id":"45200863b3860982","repo":"apache/hadoop","slug":"unresolved-topology-mapping-for-host-hostname","errorCode":null,"errorMessage":"Unresolved topology mapping for host {hostname}","messagePattern":"Unresolved topology mapping for host (.+?)","errorType":"exception","errorClass":"UnresolvedTopologyException","httpStatus":null,"severity":"critical","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/blockmanagement/DatanodeManager.java","lineNumber":1083,"sourceCode":"   * @param node to resolve to network location\n   * @return network location path.\n   * @throws UnresolvedTopologyException if the DNS to switch mapping fails \n   *    to resolve network location.\n   */\n  private String resolveNetworkLocation (DatanodeID node) \n      throws UnresolvedTopologyException {\n    List<String> names = new ArrayList<>(1);\n    if (dnsToSwitchMapping instanceof CachedDNSToSwitchMapping) {\n      names.add(node.getIpAddr());\n    } else {\n      names.add(node.getHostName());\n    }\n    \n    List<String> rName = resolveNetworkLocation(names);\n    String networkLocation;\n    if (rName == null) {\n      LOG.error(\"The resolve call returned null!\");\n        throw new UnresolvedTopologyException(\n            \"Unresolved topology mapping for host \" + node.getHostName());\n    } else {\n      networkLocation = rName.get(0);\n    }\n    return networkLocation;\n  }\n\n  /**\n   * Resolve network locations for specified hosts\n   *\n   * @return Network locations if available, Else returns null\n   */\n  public List<String> resolveNetworkLocation(List<String> names) {\n    // resolve its network location\n    return dnsToSwitchMapping.resolve(names);\n  }\n\n  /**","sourceCodeStart":1065,"sourceCodeEnd":1101,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/blockmanagement/DatanodeManager.java#L1065-L1101","documentation":"Thrown as UnresolvedTopologyException from DatanodeManager.resolveNetworkTopology when the DNS-to-switch mapping service returns null for a datanode's address/hostname during registration or topology refresh. The NN cannot place the node into NetworkTopology without a rack location, and defaulting to a wrong rack would break placement correctness, so registration fails with this exception.","triggerScenarios":"Datanode registers (registerDatanode) or topology is refreshed while AbstractDNSToSwitchMapping.resolve() returns null — script-based mapping (net.topology.script.file.path) that exits non-zero/prints nothing for the host, TableMapping/CachedDNSToSwitchMapping cache miss with no fallback, or a custom mapper returning null.","commonSituations":"Topology script not handling a new host's IP/hostname pattern; script permission or path wrong so lookup yields nothing; mapping table (TableMapping) missing the host; DNS name vs IP mismatch in what the script receives; adding nodes without updating topology data.","solutions":["Test the mapping for the failing host: run the script manually with the exact hostname/IP the NN passes and ensure it prints a rack path (e.g., /default-rack or /dc1/rack5)","Add the host to your mapping source (script's data file, TableMapping table, or the external resolver) and restart/refresh NN","Ensure net.topology.script.file.path points to an executable script returning one network location per input line","As stopgap, configure net.topology.node.switch.mapping.impl to ScriptMapping with a default '/default-rack' branch for unknown hosts (accepts degraded placement correctness)"],"exampleFix":"# before: script returns nothing for new host 10.1.2.3\n$ echo 10.1.2.3 | /etc/hadoop/topology.sh ; echo $?  # empty -> UnresolvedTopologyException\n\n# after: script maps unknown hosts to a default rack\n#!/bin/bash\nwhile [ $# -gt 0 ]; do\n  rack=$(grep -i \"^$1 \" /etc/hadoop/topology.table 2>/dev/null | cut -d' ' -f2)\n  echo -n \"${rack:-/default-rack} \"\n  shift\ndone","handlingStrategy":"validation","validationCode":"// Validate topology resolution for a host before DN registration storm\nDNSToSwitchMapping resolver = new CachedDNSToSwitchMapping(\n    ReflectionUtils.newInstance(conf.getClass(\n        \"net.topology.node.switch.mapping.impl\",\n        ScriptBasedMapping.class, DNSToSwitchMapping.class), conf));\nList<String> loc = resolver.resolve(Arrays.asList(\"dn5.example.com\"));\nif (loc == null || loc.get(0) == null || loc.get(0).isEmpty()) {\n  throw new IllegalStateException(\"Topology mapping returns nothing for dn5 — fix script/table\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Make topology scripts/table cover every DN host and IP form, with a /default-rack fallback branch","Test the script manually with each new node's exact hostname and IP before adding it","Keep the mapping executable and readable by the NN user","Monitor NN registration metrics; UnresolvedTopologyException means the node never joins"],"tags":["hdfs","network-topology","datanode-registration","dns","rack-awareness","configuration"],"backgroundTag":"rack-topology-resolution-failed","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}