apache/hadoop · error · IOException

Unresolved host: {}

Error message

Unresolved host: {}

What it means

DFSUtilClient.isLocalAddress(InetSocketAddress) decides whether a target is loopback/local (used for short-circuit read feasibility). Java's InetSocketAddress can exist in an unresolved state when DNS failed at construction time; isLocalAddress refuses to guess from a hostname alone and throws IOException('Unresolved host: <addr>') whenever targetAddr.isUnresolved() is true.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/DFSUtilClient.java:745

    return String.format(format, days, hours, minutes, seconds, milliseconds);
  }

  /**
   * Converts a Date into an ISO-8601 formatted datetime string.
   */
  public static String dateToIso8601String(Date date) {
    SimpleDateFormat df =
        new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ssZ", Locale.ENGLISH);
    return df.format(date);
  }

  private static final Map<String, Boolean> localAddrMap = Collections
      .synchronizedMap(new HashMap<String, Boolean>());

  public static boolean isLocalAddress(InetSocketAddress targetAddr)
      throws IOException {
    if (targetAddr.isUnresolved()) {
      throw new IOException("Unresolved host: " + targetAddr);
    }
    InetAddress addr = targetAddr.getAddress();
    Boolean cached = localAddrMap.get(addr.getHostAddress());
    if (cached != null) {
      LOG.trace("Address {} is{} local", targetAddr, (cached ? "" : " not"));
      return cached;
    }

    boolean local = NetUtils.isLocalAddress(addr);

    LOG.trace("Address {} is{} local", targetAddr, (local ? "" : " not"));
    localAddrMap.put(addr.getHostAddress(), local);
    return local;
  }

  /** Create a {@link ClientDatanodeProtocol} proxy */
  public static ClientDatanodeProtocol createClientDatanodeProtocolProxy(
      DatanodeID datanodeid, Configuration conf, int socketTimeout,

View on GitHub (pinned to 2add963021)

Solutions

1. From the client host, verify resolution of the datanode hostname: getent hosts <dn-host> / nslookup; fix DNS or /etc/hosts accordingly.
2. Configure datanodes to register resolvable names (dfs.datanode.hostname, or ensure reverse DNS works via dns.name-resolver).
3. On Kubernetes/overlay deployments, point clients at the cluster's DNS and check ndots/search-domain settings.
4. After fixing DNS, remember JVM DNS caching (networkaddress.cache.negative.ttl) — restarting the client JVM or lowering the negative TTL clears it.

Example fix

// before
InetSocketAddress dnAddr = locatedBlock.getLocations()[0].getXferAddr(true);
boolean local = DFSUtilClient.isLocalAddress(dnAddr); // throws if unresolved

// after
InetSocketAddress dnAddr = locatedBlock.getLocations()[0].getXferAddr(true);
if (dnAddr.isUnresolved()) {
  LOG.warn("Cannot resolve datanode address {} - skipping local check", dnAddr);
  return false;
}
boolean local = DFSUtilClient.isLocalAddress(dnAddr);

if (dnSocketAddress.isUnresolved()) {
  LOG.warn("Datanode address {} is unresolved; DNS fix needed", dnSocketAddress);
  return false; // treat as non-local and surface a actionable warning
}
return DFSUtilClient.isLocalAddress(dnSocketAddress);

boolean resolvable = !targetAddr.isUnresolved(); // InetSocketAddress narrowing check

try {
  return DFSUtilClient.isLocalAddress(addr);
} catch (IOException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Unresolved host")) {
    LOG.warn("Skipping local-address check; fix DNS for {}", addr);
    return false;
  }
  throw e;
}

When it happens

Trigger: Passing an InetSocketAddress built from a hostname the client JVM could not resolve — most often the datanode address taken from LocatedBlock during block reads, checked by the short-circuit/local-read logic when the DN's registered hostname is unresolvable from the client.

Common situations: Datanodes registering hostnames the client's DNS cannot resolve (missing records, different DNS domains, Kubernetes/overlay networks without pod-name resolution); stale DNS after cluster re-IP; JVM negative-DNS caching making the failure persist after DNS is fixed; missing /etc/hosts entries on heterogeneous clusters.

Related errors

• Replica generation stamp < block generation stamp, block={bl
• Unexpected EOS from the reader
• the datanode {} failed to pass a file descriptor (might have
• {this}: slot {slotIdx} does not exist.
• {this}: invalid negative slot index {slotIdx}

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