apache/hadoop · warning · UnknownHostException

${name} is not a valid Inet address

Error message

${name} is not a valid Inet address

What it means

UnknownHostException from NetUtils.verifyHostnames when a non-null entry cannot be coerced into a URI with a host: neither new URI(name) nor the retry new URI("http://" + name) yields a non-null getHost(). This rejects names whose syntax is too broken to even extract a hostname (URISyntaxException in both attempts, or a URI with no host component). It is a syntax check, not a DNS check — nothing is resolved.

Source

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

  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");
      }
    }
  }

  private static final Pattern ipPortPattern = // Pattern for matching ip[:port]
    Pattern.compile("\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}(:\\d+)?");
  
  /**
   * Attempt to obtain the host name of the given string which contains
   * an IP address and an optional port.
   * 
   * @param ipPort string of form ip[:port]
   * @return Host name or null if the name can not be determined
   */
  public static String getHostNameOfIP(String ipPort) {
    if (null == ipPort || !ipPortPattern.matcher(ipPort).matches()) {
      return null;
    }

View on GitHub (pinned to 2add963021)

Solutions

1. Correct the entry to a plain hostname, FQDN, IP, or scheme://host form without illegal characters
2. Replace underscores and spaces (illegal in URI hosts) with dashes
3. Pre-validate entries with the same URI trick (new URI(name) / new URI("http://" + name)) to catch bad values at config load time

Example fix

// before
NetUtils.verifyHostnames(new String[] { "my_host.example.com" }); // '_' illegal in URI host -> UnknownHostException

// after
NetUtils.verifyHostnames(new String[] { "my-host.example.com" });

static boolean looksLikeHostname(String name) {
  try {
    URI u = new URI(name);
    if (u.getHost() == null) u = new URI("http://" + name);
    return u.getHost() != null;
  } catch (URISyntaxException e) { return false; }
}

catch (UnknownHostException e) { /* '<name> is not a valid Inet address' */ it is a syntax failure, not DNS: fix characters (spaces, underscores, extra colons) and re-validate; }

When it happens

Trigger: Entries containing spaces, '_', '{', '}', '|' or other characters illegal in URI hosts; names like 'host name' or 'host:port:extra'; empty strings after trim; entries that are bare schemes ('http://') with no host.

Common situations: Hand-edited host lists with stray characters; templating bugs injecting blanks; users assuming this does DNS resolution and being confused when a resolvable-but-weird name (e.g., with underscore) still fails.

Related errors

• Does not contain a valid host:port authority: ${target} (con
• null hostname found
• Wrong length: {digest.length}
• Wrong length: {hex.length}
• Not a hex character: {c}

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