apache/hadoop · critical · UnresolvedTopologyException

Unresolved topology mapping for host {hostname}

Error message

Unresolved topology mapping for host {hostname}

What it means

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.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/blockmanagement/DatanodeManager.java:1083

   * @param node to resolve to network location
   * @return network location path.
   * @throws UnresolvedTopologyException if the DNS to switch mapping fails 
   *    to resolve network location.
   */
  private String resolveNetworkLocation (DatanodeID node) 
      throws UnresolvedTopologyException {
    List<String> names = new ArrayList<>(1);
    if (dnsToSwitchMapping instanceof CachedDNSToSwitchMapping) {
      names.add(node.getIpAddr());
    } else {
      names.add(node.getHostName());
    }
    
    List<String> rName = resolveNetworkLocation(names);
    String networkLocation;
    if (rName == null) {
      LOG.error("The resolve call returned null!");
        throw new UnresolvedTopologyException(
            "Unresolved topology mapping for host " + node.getHostName());
    } else {
      networkLocation = rName.get(0);
    }
    return networkLocation;
  }

  /**
   * Resolve network locations for specified hosts
   *
   * @return Network locations if available, Else returns null
   */
  public List<String> resolveNetworkLocation(List<String> names) {
    // resolve its network location
    return dnsToSwitchMapping.resolve(names);
  }

  /**

View on GitHub (pinned to 2add963021)

Solutions

1. 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)
2. Add the host to your mapping source (script's data file, TableMapping table, or the external resolver) and restart/refresh NN
3. Ensure net.topology.script.file.path points to an executable script returning one network location per input line
4. As stopgap, configure net.topology.node.switch.mapping.impl to ScriptMapping with a default '/default-rack' branch for unknown hosts (accepts degraded placement correctness)

Example fix

# before: script returns nothing for new host 10.1.2.3
$ echo 10.1.2.3 | /etc/hadoop/topology.sh ; echo $?  # empty -> UnresolvedTopologyException

# after: script maps unknown hosts to a default rack
#!/bin/bash
while [ $# -gt 0 ]; do
  rack=$(grep -i "^$1 " /etc/hadoop/topology.table 2>/dev/null | cut -d' ' -f2)
  echo -n "${rack:-/default-rack} "
  shift
done

// Validate topology resolution for a host before DN registration storm
DNSToSwitchMapping resolver = new CachedDNSToSwitchMapping(
    ReflectionUtils.newInstance(conf.getClass(
        "net.topology.node.switch.mapping.impl",
        ScriptBasedMapping.class, DNSToSwitchMapping.class), conf));
List<String> loc = resolver.resolve(Arrays.asList("dn5.example.com"));
if (loc == null || loc.get(0) == null || loc.get(0).isEmpty()) {
  throw new IllegalStateException("Topology mapping returns nothing for dn5 — fix script/table");
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Datanode denied communication with namenode because hostname
• Failed to add {}: You cannot have a rack and a non-rack node
• Configured cluster topology should be org.apache.hadoop.net.
• Datanode denied communication with namenode because the host
• Can not create a Path from a null string

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