apache/hadoop · warning · UnknownHostException

null hostname found

Error message

null hostname found

What it means

UnknownHostException('null hostname found') from NetUtils.verifyHostnames — a validation helper that sanity-checks an array of hostnames/IPs (typically proxy or cluster node lists). It throws on the first null entry before doing any URI-based syntax checks. Its presence means the caller passed an array containing nulls, which usually traces back to how the list was built (e.g., splitting an empty or malformed config string).

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/net/NetUtils.java:678

   */
  public static List<String> normalizeHostNames(Collection<String> names) {
    List<String> hostNames = new ArrayList<String>(names.size());
    for (String name : names) {
      hostNames.add(normalizeHostName(name));
    }
    return hostNames;
  }

  /**
   * Performs a sanity check on the list of hostnames/IPs to verify they at least
   * appear to be valid.
   * @param names - List of hostnames/IPs
   * @throws UnknownHostException Unknown Host Exception.
   */
  public static void verifyHostnames(String[] names) throws UnknownHostException {
    for (String name: names) {
      if (name == null) {
        throw new UnknownHostException("null hostname found");
      }
      // The first check supports URL formats (e.g. hdfs://, etc.). 
      // java.net.URI requires a schema, so we add a dummy one if it doesn't
      // have one already.
      URI uri = null;
      try {
        uri = new URI(name);
        if (uri.getHost() == null) {
          uri = new URI("http://" + name);
        }
      } catch (URISyntaxException e) {
        uri = null;
      }
      if (uri == null || uri.getHost() == null) {
        throw new UnknownHostException(name + " is not a valid Inet address");
      }
    }
  }

View on GitHub (pinned to 2add963021)

Solutions

1. Filter nulls out of the array before validation: Arrays.stream(names).filter(Objects::nonNull)
2. Fix the upstream list construction so empty config tokens are dropped rather than stored as null
3. Log the raw array (with null markers) when validation fails to identify the producing property

Example fix

// before
String[] hosts = parseHosts(conf); // may contain nulls
NetUtils.verifyHostnames(hosts); // UnknownHostException: null hostname found

// after
String[] hosts = Arrays.stream(parseHosts(conf))
    .filter(Objects::nonNull).toArray(String[]::new);
NetUtils.verifyHostnames(hosts);

boolean hasNull = Arrays.stream(names).anyMatch(Objects::isNull);
if (hasNull) throw new IllegalStateException("host array contains null entries (check list construction)");

static String[] nonNullHosts(String[] names) {
  return names == null ? new String[0]
      : Arrays.stream(names).filter(Objects::nonNull).toArray(String[]::new);
}

When it happens

Trigger: verifyHostnames(new String[] { "host1", null, "host2" }); arrays produced by a config split where a token was empty and stored as null; code mapping an optional setting straight into the array without a null filter.

Common situations: Proxy configurations (e.g., hadoop.http.proxy...) where an unset optional host leaks null into the list; list parsing that uses a map returning null for missing keys; refactors changing array construction order.

Related errors

• ${name} is not a valid Inet address
• null component type not allowed
• null value not allowed
• null valueClass
• Wrong length: {digest.length}

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