{"record":{"id":"cf2abb874cfecf38","repo":"apache/hadoop","slug":"unresolved-host","errorCode":null,"errorMessage":"Unresolved host: {}","messagePattern":"Unresolved host: (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/DFSUtilClient.java","lineNumber":745,"sourceCode":"    return String.format(format, days, hours, minutes, seconds, milliseconds);\n  }\n\n  /**\n   * Converts a Date into an ISO-8601 formatted datetime string.\n   */\n  public static String dateToIso8601String(Date date) {\n    SimpleDateFormat df =\n        new SimpleDateFormat(\"yyyy-MM-dd'T'HH:mm:ssZ\", Locale.ENGLISH);\n    return df.format(date);\n  }\n\n  private static final Map<String, Boolean> localAddrMap = Collections\n      .synchronizedMap(new HashMap<String, Boolean>());\n\n  public static boolean isLocalAddress(InetSocketAddress targetAddr)\n      throws IOException {\n    if (targetAddr.isUnresolved()) {\n      throw new IOException(\"Unresolved host: \" + targetAddr);\n    }\n    InetAddress addr = targetAddr.getAddress();\n    Boolean cached = localAddrMap.get(addr.getHostAddress());\n    if (cached != null) {\n      LOG.trace(\"Address {} is{} local\", targetAddr, (cached ? \"\" : \" not\"));\n      return cached;\n    }\n\n    boolean local = NetUtils.isLocalAddress(addr);\n\n    LOG.trace(\"Address {} is{} local\", targetAddr, (local ? \"\" : \" not\"));\n    localAddrMap.put(addr.getHostAddress(), local);\n    return local;\n  }\n\n  /** Create a {@link ClientDatanodeProtocol} proxy */\n  public static ClientDatanodeProtocol createClientDatanodeProtocolProxy(\n      DatanodeID datanodeid, Configuration conf, int socketTimeout,","sourceCodeStart":727,"sourceCodeEnd":763,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/DFSUtilClient.java#L727-L763","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["From the client host, verify resolution of the datanode hostname: getent hosts <dn-host> / nslookup; fix DNS or /etc/hosts accordingly.","Configure datanodes to register resolvable names (dfs.datanode.hostname, or ensure reverse DNS works via dns.name-resolver).","On Kubernetes/overlay deployments, point clients at the cluster's DNS and check ndots/search-domain settings.","After fixing DNS, remember JVM DNS caching (networkaddress.cache.negative.ttl) — restarting the client JVM or lowering the negative TTL clears it."],"exampleFix":"// before\nInetSocketAddress dnAddr = locatedBlock.getLocations()[0].getXferAddr(true);\nboolean local = DFSUtilClient.isLocalAddress(dnAddr); // throws if unresolved\n\n// after\nInetSocketAddress dnAddr = locatedBlock.getLocations()[0].getXferAddr(true);\nif (dnAddr.isUnresolved()) {\n  LOG.warn(\"Cannot resolve datanode address {} - skipping local check\", dnAddr);\n  return false;\n}\nboolean local = DFSUtilClient.isLocalAddress(dnAddr);","handlingStrategy":"validation","validationCode":"if (dnSocketAddress.isUnresolved()) {\n  LOG.warn(\"Datanode address {} is unresolved; DNS fix needed\", dnSocketAddress);\n  return false; // treat as non-local and surface a actionable warning\n}\nreturn DFSUtilClient.isLocalAddress(dnSocketAddress);","typeGuard":"boolean resolvable = !targetAddr.isUnresolved(); // InetSocketAddress narrowing check","tryCatchPattern":"try {\n  return DFSUtilClient.isLocalAddress(addr);\n} catch (IOException e) {\n  if (e.getMessage() != null && e.getMessage().startsWith(\"Unresolved host\")) {\n    LOG.warn(\"Skipping local-address check; fix DNS for {}\", addr);\n    return false;\n  }\n  throw e;\n}","preventionTips":["Check isUnresolved() right after constructing an InetSocketAddress from remote-supplied hostnames.","Test DNS resolution from every client environment (different domain, K8s, CI) against actual datanode hostnames.","Mind JVM negative DNS caching (networkaddress.cache.negative.ttl) — a fixed DNS may need a JVM restart to take effect."],"tags":["hdfs","dns","network","short-circuit-read","datanode"],"backgroundTag":"dns-resolution-failed","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}