apache/hadoop · error · IllegalArgumentException

Does not contain a valid host:port authority: ${target} (con

Error message

Does not contain a valid host:port authority: ${target} (configuration property '${configName}')

What it means

IllegalArgumentException from NetUtils.createSocketAddr when the target parsed into a URI but does not describe a pure host:port authority: host is null, port is negative, or (when no 'scheme://' was present) the string carries a non-empty path component. The message echoes the offending target and the configuration property name when provided. This is the standard 'bad service address' error for properties like fs.defaultFS or YARN RM addresses.

Source

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

    }
    if (target == null) {
      throw new IllegalArgumentException("Target address cannot be null." +
          helpText);
    }
    target = target.trim();
    boolean hasScheme = target.contains("://");
    URI uri = createURI(target, hasScheme, helpText, useCacheIfPresent);

    String host = uri.getHost();
    int port = uri.getPort();
    if (port == -1) {
      port = defaultPort;
    }
    String path = uri.getPath();

    if ((host == null) || (port < 0) ||
        (!hasScheme && path != null && !path.isEmpty())) {
      throw new IllegalArgumentException(
          "Does not contain a valid host:port authority: " + target + helpText
      );
    }
    if (isResolved) {
      return createSocketAddrForHost(host, port);
    }
    return InetSocketAddress.createUnresolved(host, port);
  }

  private static final long URI_CACHE_SIZE_DEFAULT = 1000;
  private static final long URI_CACHE_EXPIRE_TIME_DEFAULT = 12;
  private static final Cache<String, URI> URI_CACHE = CacheBuilder.newBuilder()
      .maximumSize(URI_CACHE_SIZE_DEFAULT)
      .expireAfterWrite(URI_CACHE_EXPIRE_TIME_DEFAULT, TimeUnit.HOURS)
      .build();

  private static URI createURI(String target,
                               boolean hasScheme,

View on GitHub (pinned to 2add963021)

Solutions

  1. Write the address as 'host:port' or 'scheme://host:port' exactly, no path, no trailing slash
  2. Bracket IPv6 literals: 'hdfs://[2001:db8::1]:9000'
  3. Check the property named in the message for accidental characters (trailing '/', spaces, smart quotes from copy-paste)
  4. Ensure a port is present or a valid defaultPort is passed by the calling API

Example fix

<!-- before -->
<property><name>fs.defaultFS</name><value>myhost:8020/typo</value></property> <!-- path without scheme -> IllegalArgumentException -->

<!-- after -->
<property><name>fs.defaultFS</name><value>hdfs://myhost:8020</value></property>
Defensive patterns

Strategy: validation

Validate before calling

URI u = URI.create(target.contains("://") ? target : "dummyscheme://" + target);
if (u.getHost() == null || u.getPort() < -1 || (!target.contains("://") && u.getPath() != null && !u.getPath().isEmpty())) {
  throw new IllegalStateException("bad address: " + target);
}

Try / catch

catch (IllegalArgumentException e) { /* 'Does not contain a valid host:port authority' */ the message includes the raw value and property: fix format and reload config; }

Prevention

When it happens

Trigger: Values like 'hdfs://:9000' (empty host), 'host:port/path' without a scheme (path is rejected), 'hdfs://host:port/junk' is fine only because hasScheme is true — but a port of '-1' after parsing with no default, or targets such as 'localhost:notaport', produce invalid components that fail here or in createURI.

Common situations: Missing port where the caller passes defaultPort=-1; stray slashes or whitespace after trimming; IPv6 addresses written unbracketed so the URI host comes back null; copied config with 'hdfs://host:9000/extra/path' where the path makes no sense for a service address... path only matters without scheme, so typical hits are scheme-less 'host:port/path' or empty-host forms.

Related errors

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